feat(plan): state the current code before the design, and log settled decisions - #109
Merged
zhen8838 merged 2 commits intoAug 18, 2026
Merged
Conversation
… decisions A plan's design rested on claims about the code that nothing made the author check, and the reasoning behind it was rewritten in place each time the design moved -- so a reader could not tell whether the root had moved or only a detail. `## Description` now carries two sections. `### Current state` states the mechanism the code implements today, what is there and what is missing, one bullet per claim, each citing a path; a claim with nothing to point at is the one that turns out to be wrong. `### Decisions` is append-only: when an answer changes, a record supersedes the earlier one and the earlier text stays, so the trajectory is readable. Both are required, and their shape is checked. `#### Plan` is gone. Its step list was written by whoever was not implementing and went stale as soon as the milestones were restructured; `#### Depends` and `##### Delivered` already hold what an implementer needs. The finalizer reads structure from a CommonMark parse instead of a line scan, so a heading, a fence, or a marker is whatever the parser says it is. That removes the hand-rolled fence masking, heading matching, section bounds, bullet extraction, and marker scanning, along with a dead helper and the `--role` scaffolding left by a Preflight block the template no longer has.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
check. Measured while writing the two plans under
docs/plans/analyze-cost-model/:the claims that later turned out wrong were the ones with nothing to point at.
could not tell whether the root had moved or only a detail.
#### Planheld a step list written by whoever was not implementing. It wentstale as soon as a reviewer restructured the milestones, and nothing read it.
What
### Current state(required): the mechanism the code implements today, what isthere and what is missing. One bullet per claim, each citing a path in backticks.
No design — the gap is the finding, not the fix.
### Decisions(required, orNone.): append-only. When an answer changes arecord supersedes the earlier one and the earlier text stays. Ids must be unique
and a
Supersedes D<n>must resolve, so a supersede cannot be a rewrite wearingthe shape of a record.
#### Planremoved; writing it now fails.#### Dependsand##### Deliveredalready hold what an implementer needs.
writes the current state, pass 2 writes the Delivered shapes and stops for the
author, pass 3 writes the rest.
which drops the hand-rolled fence masking, heading matching, section bounds,
bullet extraction and marker scanning, plus a dead helper and the
--rolescaffolding left behind by a Preflight block the template no longer has.
643 → 503 lines while gaining three checks.
Contract
this fails to finalize until it gains a current state and a decision log.
docs/plansis gitignored, so onlyTEMPLATE.mdis hook-checked; plans finalizeon demand.
--roleis removed from the CLI. Nothing passed it.markdown-it-pyis imported and not declared; it resolves today throughrich.Local tooling only — CI reaches it through the same resolution.
Risk
eleven mutations of the template, one per rule. Both agree on all three plans;
where the exit codes match the new one reports the heading violation first, which
is the cause rather than a downstream symptom.
plans are gitignored. Ids and supersede targets are checked; the discipline is not.