Skip to content

feat(plan): state the current code before the design, and log settled decisions - #109

Merged
zhen8838 merged 2 commits into
tile-ai:mainfrom
zhen8838:feat/plan-current-state-and-decisions
Aug 18, 2026
Merged

feat(plan): state the current code before the design, and log settled decisions#109
zhen8838 merged 2 commits into
tile-ai:mainfrom
zhen8838:feat/plan-current-state-and-decisions

Conversation

@zhen8838

Copy link
Copy Markdown
Collaborator

Why

  • A plan's design rested on claims about the code that nothing made the author
    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.
  • The reasoning was rewritten in place each time the design moved, so a reader
    could not tell whether the root had moved or only a detail.
  • #### Plan held a step list written by whoever was not implementing. It went
    stale as soon as a reviewer restructured the milestones, and nothing read it.

What

  • ### Current state (required): the mechanism the code implements today, what is
    there 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, or None.): append-only. When an answer changes a
    record 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 wearing
    the shape of a record.
  • #### Plan removed; writing it now fails. #### Depends and ##### Delivered
    already hold what an implementer needs.
  • The top comment reads as instructions for starting a plan: pass 1 audits and
    writes the current state, pass 2 writes the Delivered shapes and stops for the
    author, pass 3 writes the rest.
  • The finalizer reads structure from a CommonMark parse rather than a line scan,
    which drops the hand-rolled fence masking, heading matching, section bounds,
    bullet extraction and marker scanning, plus a dead helper and the --role
    scaffolding left behind by a Preflight block the template no longer has.
    643 → 503 lines while gaining three checks.

Contract

  • Two newly required sections and one removed section: every plan written before
    this fails to finalize
    until it gains a current state and a decision log.
    docs/plans is gitignored, so only TEMPLATE.md is hook-checked; plans finalize
    on demand.
  • --role is removed from the CLI. Nothing passed it.
  • markdown-it-py is imported and not declared; it resolves today through rich.
    Local tooling only — CI reaches it through the same resolution.

Risk

  • Verified by differentially running old and new over every plan available and by
    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.
  • "Append-only" cannot be checked from one file version — it needs history, and
    plans are gitignored. Ids and supersede targets are checked; the discipline is not.

… 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.
@zhen8838
zhen8838 merged commit 6b6e821 into tile-ai:main Aug 18, 2026
1 check passed
@zhen8838
zhen8838 deleted the feat/plan-current-state-and-decisions branch August 18, 2026 04:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant