Skip to content

English · Español

00 — Closing a project well

🇪🇸 Cerrar un proyecto es una habilidad distinta de empezarlo. La tentación es seguir construyendo; el trabajo es parar, documentar, y dejar el sistema en un estado que un futuro tú o un futuro extraño pueda recoger.

What "closing" means

After 40 phases, the temptation is to add one more thing. One more feature. One more optimisation. One more polish on the tutor agent.

Don't. Closing is a separate skill from building. The deliverables of closing are:

  1. A system that is in a known state. Threats either closed or explicitly accepted. Tests pass. Docs match code. CI green.
  2. A written record of how you got here. The postmortem. Not for anyone else (although others may read it) — for the next-you, who in six months will look at this codebase and not remember why X is the way it is.
  3. A plan for what's next. Because the project ends; learning doesn't.

If you skip the closing work and "just start the next thing," you'll lose the lessons. The 40-phase journey is the data. The postmortem is what turns that data into knowledge.

The three deliverables, in priority order

Priority 1 — Hardening

Walk security/THREATS.md line by line. For each open item:

  • Close it. Implement the mitigation. Add a test. Update the threat to "mitigated by X (verified in test Y)."
  • Accept it. Decide that the cost of fixing is higher than the risk. Write the rationale in the threat doc. ("Accepted: we run on a single-tenant CPU; the supply-chain risk is bounded by pip-audit and weekly review. Reassess if we add a hosted endpoint.")
  • Punt it. Decide it's out of scope for this project but worth noting for the next one. Move it to READING_LIST.md as a future direction.

The point is to leave zero unstated risks. A threat doc with stale "TODO" items is worse than no doc — it lies about the system's state.

Priority 2 — Postmortem

Write the journey as if it were a long-running incident. Not because the project went badly — it didn't — but because the postmortem format forces honesty about what was hard, what was lucky, and what almost broke.

A good postmortem has five sections (more in file 01): summary, timeline, contributing factors, lessons, action items. The action items here are for future projects, not this one.

Priority 3 — Reading list

The reading list isn't a bookmark dump. It's a curriculum recommendation for "what to do next." Each entry has a one-sentence "why" and a one-sentence "what to do with it." Twenty good entries beat two hundred mediocre ones.

Why this order

Hardening first because dishonesty in the threat model carries forward — accept it now or you'll work around it in the next project and not know why.

Postmortem second because the reading list depends on knowing what you're missing — which requires having articulated what you have.

Reading list last because it's the part that points away from the project. Doing it first leaks attention out of the closing work.

The blameless framing

The postmortem mentions Phase 18's training loss being broken for two days because of a np.argmax axis bug. The blameful version: "Borja made a sloppy mistake." The blameless version: "The Mini-GPT's training signal was silently degraded for ~48 hours; root cause was an axis off-by-one that the existing tests didn't catch; the contributing factor was that Phase 18's test suite covered correctness on a 4-token sequence but not the multi-batch case."

The blameless framing is not about being kind to past-Borja. It's about producing actionable lessons. "Be more careful" is not a lesson; "add a multi-batch shape assertion to the training step" is.

For Phase 40's postmortem: every incident gets a structural cause, not a personal one.

When you might break this advice

  • If you discover a critical security issue during the hardening pass, fix it. Don't accept it.
  • If a deliverable is objectively wrong (the postmortem is unreadable, the reading list is mostly broken links), redo it. Closing well includes redoing your closing work.
  • If the project's stakeholders changed — Borja decided mid-journey to point the capstone at Spanish learners only — update the docs to reflect the actual final state.

Otherwise: resist the urge to expand scope.

A meta-lesson

Many projects never end. They peter out, get abandoned, or accumulate "we'll polish it later" forever. The act of formally closing — writing the postmortem, marking the ROADMAP green, doing the reading list — is what turns the project from a half-finished thing into a finished thing that taught you something.

The next project will be better because this one was finished, not because it was perfect.

What this file does NOT cover

  • The postmortem format itself. Next file.
  • What "good architectural survival" looks like. File 02.
  • The reading list curation method. Lab 02.

Next: 01-postmortem-structure.md