Skip to content

English · Español

Lab 01 — Write the journey postmortem

🇪🇸 La autopsia del viaje. Cinco secciones, estructura canónica. No es un diario; es un documento técnico con narrativa. Mínimo 1500 palabras.

Objective

Produce docs/phase-40-hardening-postmortem/postmortem.md: a structured, blameless postmortem of the 40-phase journey through lynx-cortex. Length: ≥ 1500 words.

Setup

  • All 40 PHASE_NN_REPORT.md files.
  • The learners/borja/journal/YYYY-MM-DD.md series.
  • PROPOSAL_REVIEW.md for the architectural-decision ledger.
  • git log --oneline --decorate for the timeline.
  • The decision-survival analysis from theory/02-decision-survival.md (to inform §3).

Tasks

Follow the five-section template from theory/01-postmortem-structure.md:

Section 1 — Summary (100-200 words)

Write last. Read all the other sections first, then distill them into a single paragraph that captures: - What the project was (one sentence). - What shipped (one sentence). - What didn't ship (one sentence). - The headline lesson (one sentence).

Section 2 — Timeline

Pull from git log and the PHASE_NN_REPORT.md files. One line per phase. Format:

2026-MM-DD — Phase NN <Name>. <One-line outcome>. [link to PHASE_NN_REPORT.md or commit SHA]

Add annotations for the bumps:

2026-03-04 — Phase 18 training loop kickoff.
2026-03-05 — TROUGH: training loss flat at 4.16; root cause discovered to be axis-1 vs axis-2 bug in attention mask. Fix in commit abc1234.
2026-03-06 — Loss curve resumes expected descent.

Include 5-10 such "bumps." If the journey was too smooth to find any, you're either lying to yourself or you didn't take any risks — both deserve a line in §3.

Section 3 — Contributing factors

Aim for 5-8 factors. Mix structural and one-off. For each, write 2-4 sentences:

Structural factors (examples): - The NumPy-first / hand-built / framework-last policy. - The per-phase ritual (Plan → Build → Teach → Run → Report → Reflect). - The bilingual policy. - The CPU-only constraint forcing microscopic corpus. - The §A13 verb-grammar pivot from C-strings.

One-off events (examples): - The axis bug in Phase 18. - The Pydantic v1 → v2 migration in Phase 30. - The Phase 22 KV cache invalidating Phase 21's sampler-as-written. - Quota / cost / hardware events.

For each, write the structural cause, not the personal one (per the blameless principle).

Section 4 — Lessons learned

3-7 generalisable principles. Each in the rule + why + how to apply format:

Lesson 1: Build the eval set before the model. Why: The §A13 verb corpus existed in Phase 12 — six phases before the model. Every later evaluation had unambiguous ground truth. How to apply next: On the next project, spend the first 10% of time on eval design. Refuse to write training code until the eval set is concrete and small.

Lesson 2: Tested intuition beats elegant theory. Why: The Pre-LN choice (Phase 17) was justified by an explicit ablation comparison, not by "everyone uses it." The 30-line ablation was worth the day. How to apply next: Whenever choosing between two equally-cited options, run a 1-hour ablation. Do not skip.

Extract the lessons that will change how the next project starts — not generic platitudes.

Section 5 — Action items

3-5 concrete actions for future projects. Format:

[Action] by [date]. Owner: [future-Borja]. Success criterion: [observable signal].

Examples:

Adopt the BLUEPRINT.md rule on the next project from day 1. Owner: future-Borja. Success criterion: any new src/ module created has a BLUEPRINT.md within 48 hours of creation.

Schedule a 6-month re-read of this postmortem (calendar event for 2026-11-23). Owner: future-Borja. Success criterion: a calendar event exists with a link to this file.

Add an "off-ramp 1" check-in at 2026-08-23 (3 months out). Did Borja start the chosen next project? Owner: future-Borja. Success criterion: a journal entry on or before that date answering yes/no with reasoning.

Word-count check

Run a quick word count after each section. The final document should be ≥ 1500 words.

wc -w docs/phase-40-hardening-postmortem/postmortem.md

If it's under, examine which sections are thin. Don't pad — investigate which sections you under-developed.

Acceptance

  • postmortem.md exists at docs/phase-40-hardening-postmortem/postmortem.md.
  • All five sections present, in the canonical order.
  • Word count ≥ 1500.
  • Timeline contains specific dates, phases, and at least 5 annotated bumps.
  • Contributing factors section names ≥ 5 factors.
  • Lessons section has 3-7 lessons, each with rule/why/how-to-apply.
  • Action items has 3-5 entries, each dated and with a success criterion.
  • Markdown renders cleanly (no broken links).

Pitfalls

  • Skipping the timeline. Without the timeline, the postmortem has no spine. Don't cut it.
  • Writing the summary first. Write it last; it's a distillation.
  • Cosmetic blameless language hiding personal blame. "Borja made a mistake" reworded to "an error occurred" is not blameless — it's evasive. Blameless means identifying the structural cause that allowed the mistake. Always have a structural cause.
  • Too many lessons. Seven is the max. More than seven means you didn't filter; the reader will skim and skip.
  • Action items without dates or success criteria. Without them, action items are wishes. Add both, or delete the action item.
  • Re-litigating decisions. A postmortem is not the place to argue that, say, Phase 17 should have used Post-LN. State the decision, state the outcome, move on. Save second-guessing for the next-project charter.

Stretch

  • Embed key diagrams. The decision-survival waterfall (from theory/02-decision-survival.md), the cost-vs-learning plot (from PHASE_40_PLAN.md §2.1).
  • Add a "what surprised me most" subsection. Three to five concrete surprises from the journey. These are often the highest-signal lessons.

Next: 02-reading-list.md