plan-md-evolution

plan-md-evolution

[[plan-md-authoring]] bootstraps PLAN.md at project start. This skill takes over for the entire rest of the project lifecycle — every phase advance, every decision, every blocker, every iteration. PLAN.md is the durable contract; evolution is what keeps it durable.

This skill fires every time [[ralph-loop]] step 5 runs ("update PLAN.md after each phase"). It's not optional — drift between PLAN.md and disk truth is what KC's hard-tracking principle was designed to prevent (KC: a sibling verification harness). Disk is truth; PLAN.md is the human-readable summary of the truth.

Soft enforcement. The six patterns below are John's defaults — suggestions grounded in real project experience. If a template ships its own evolution patterns (different Log format, different renumbering convention, different Open-Decisions schema), follow that instead. The load-bearing principles are: stay auditable (disk is truth, append-only Log), don't silently corrupt PLAN.md, and surface blockers to the user. The specific forms are flexible.

Relationship to [[phase-design]]. Phase-design teaches the design judgment ("when is iteration the right move? what makes a good phase?"); this skill teaches the maintenance mechanics ("how to subdivide in PLAN.md, what to log, how to renumber"). When you're deciding whether to subdivide, consult phase-design. When you're doing the actual subdivide, this skill drives.

The maintenance jobs

Seven recurring patterns. Use the right one for the situation:

1. Mark a phase done. When a phase's done criteria are met (verified via [[workspace-discipline]] disk checks), update its section header and append to the Log.
2. Subdivide a phase. When you discover mid-flight that a phase has too much in it ("extract knowledge from corpus" turns out to need both summary-extraction and structured-extraction as separate sub-phases). Append a Log entry, split the phase into N sub-phases, keep the original's Done criteria as the union of the children's.
3. Merge phases. When two phases turn out to be tightly coupled and can't run independently. Less common than subdivide; collapses two sections into one.
4. Drop a phase. When a phase's intent no longer applies (the active template's "research images" phase isn't needed because this corpus is text-only). Mark it dropped in the Log with rationale; keep the section as a struck-through stub for traceability.
5. Insert a phase. When you discover a phase you didn't anticipate (the corpus turned out to need a coreference-resolution step). Append a Log entry; insert the new phase at the right position; renumber subsequent ones.
6. Promote a TBD to concrete. When you wrote "Phase 5: TBD — decide after Phase 4 ships" and now Phase 4 is done. Settle Phase 5's intent + skills + artifacts + done criteria with the user.
7. Distill lessons. The phase boundary is also where the run's learning gets captured: write what fought reality this phase into <project>/.john/lessons/ (per [[skill-evolution]] — conditional form, evidence pointers, scope guess), and present any project-local skill-override drafts for sign-off alongside the phase summary. The Log references lesson files; it doesn't duplicate them.