Plan format
This document defines the normative format for the PLAN artifact of
the lifecycle introduced in
ADR-0010 — specifically
Stage definitions → PLAN. It is the contract that every plan SHALL
satisfy and the schema that the plan reviewer (per AGENTS.md →
Plan review protocol) and the retroactive routing engine
(issue #172) will rely on. The format is mandated by
specs/0004-plan-format-and-review.md
(R1..R11) and, for the tier-conditioned mandatory set below, by
specs/0138-tier-bounded-plan-artifacts-and-loops.md
(R1); every section below traces back to one of these requirements.
Not a file — a comment
A plan is a GitHub comment posted on the logbook issue, not a
file in the repository. Consequently a plan has no YAML
frontmatter and no file path. Future readers SHOULD NOT graft a
frontmatter schema by analogy with
docs/spec-format.md: the spec format applies to
artifacts that ship on main and need machine-readable metadata; the
plan format applies to discussion-thread comments whose machine-read
fields (id, status, related issue) are already carried by the GitHub
issue itself.
Header conventions
The first line of every plan comment SHALL be a level-2 heading matching exactly one of the patterns below.
| Comment kind | Header | Requirement |
|---|---|---|
| Initial plan | ## PLAN — issue #<N> (spec <NNNN>) |
R1 |
| Revision | ## PLAN v<N+1> — issue #<N> (spec <NNNN>) — revision after <trigger> |
R9 |
| Review (pass 1) | ## PLAN review — issue #<N> (or ## PLAN review of v1 — issue #<N>) followed by ### Verdict: APPROVE or ### Verdict: REQUEST CHANGES on the next non-empty line |
R6 |
| Review (pass M ≥ 2) | ## PLAN review of v<M> — issue #<N> followed by ### Verdict: APPROVE or ### Verdict: REQUEST CHANGES on the next non-empty line |
R6 |
<N> is the logbook issue number, <NNNN> the zero-padded spec id,
<M> the plan revision ordinal being judged (v1, v2, etc.),
and <trigger> is a short noun phrase describing why the revision
exists (DEV finding, user request, REQUEST CHANGES review,
etc.). ## PLAN review — issue #<N> is accepted as a backward-compatible
alias for ## PLAN review of v1 — issue #<N>.
Mandatory body sections
An initial or revised plan comment SHALL contain the level-3 headings below that are mandatory at its complexity tier (see Tier-conditioned mandatory set), in this order, with their text matching verbatim (case-sensitive, no trailing punctuation). A future plan linter will rely on header presence and ordering to validate conformance.
1. ### Approach — one paragraph, plain prose. Captures the
semantics of the plan — what stance the implementation takes — in a
single breath. No file-by-file enumeration here; that belongs in
### Steps.
2. ### Steps — ordered list. Each step SHALL name the concrete
file path(s) it touches and a one-line description of the edit. A step
MAY carry the [P] marker as its first token (after the list number)
to indicate the step CAN run in parallel with the preceding step;
absence of [P] means strictly sequential (R4).
1. Edit `path/to/a.md` — add the X section after Y.
2. [P] Edit `path/to/b.md` — refresh the Z table.
3. Run `scripts/build-components.sh` and stage the regenerated outputs.
3. ### Blast radius — bullet list. Each bullet names one of: an
affected code path, a downstream ticket, a build output, a version-bump
trigger (per AGENTS.md → Version Bump Convention), or a CLI-matrix
trigger surface (per AGENTS.md → CLI Matrix Maintenance). When a
category is genuinely empty for the ticket, state so explicitly
(Build outputs: none.) rather than omitting the bullet — silence
reads as oversight.
4. ### Alternatives considered and rejected — at least one
alternative, each followed by a one-line rationale. The purpose is to
surface the design space the author traversed; a plan with zero
rejected alternatives is rarely a plan that explored options.
5. ### Rollback strategy — one paragraph. Names the concrete
revert path (commit revert, configuration rollback, data migration
reversal, etc.) and any coordination required with downstream tickets
or deployed components.
Tier-conditioned mandatory set
The complexity tier declared in the ticket's spec frontmatter (per ADR-0010 → Complexity tiers and team sizing) determines which of the five sections above are mandatory:
- At every tier —
trivial,small,standard, andlarge—### Approachand### Stepsare mandatory for a structured plan comment; the sole exception is thetrivial-tier one-line plan confirmation admitted by spec 0138 R2 and by ADR-0010 → Stage definitions and transition rules rule 3, which is a sufficient PLAN artifact without either section. That confirmation still carries the Initial plan header## PLAN — issue #<N> (spec <NNNN>)from Header conventions above, so it stays discoverable under the header patterns this document's preamble names and satisfiesspecs/0004-plan-format-and-review.mdR1; it is exempt from the level-3 section set alone. - At
trivialandsmalltiers,### Blast radius,### Alternatives considered and rejected, and### Rollback strategyMAY be omitted; when present, they SHALL keep the format defined above. - At
standardandlargetiers, all five sections remain mandatory (R1 of spec 0138).
These clauses bound the plan's size and the loop's length; they remove no item from the reviewer's checklist at any tier.
Optional sections
### Risks — discrete risks with a one-line mitigation or
acceptance note each. When present, the section SHALL appear after
### Rollback strategy (R3). Plans that surface non-trivial
uncertainty SHOULD include it; plans whose blast radius is fully
bounded MAY omit it.
### Finding traceability (or ### Revision rationale & traceability) —
a Markdown table mapping every reviewer-minted ID (v<N>-F<M>) raised across
prior review passes to its resolution or rationale in the revised plan comment.
Mandatory when revising a plan in response to a REQUEST CHANGES verdict.
The table SHALL carry the schema:
| Plan Ver | Finding ID | Resolution / Rationale | Step |
|---|---|---|---|
| v1 | v1-F1 | Added preconditions step | Step 1 |
| v1 | v1-F2 | Clarified scope boundary | Step 3 |
The row count of addressed reviewer-minted IDs SHALL equal the total number
of findings raised across prior review passes (per docs/plan-review-protocol.md
→ Countable invariant).
Finding tag schema
Every plan-review finding SHALL carry a reviewer-minted identifier in its header
(v<N>-F<M>) and exactly one class: field whose value is one of tech, arch,
or spec (R7). The class drives the loop target of the retroactive review loop;
the routing matrix is defined once, in docs/retroactive-loop.md
→ Routing matrix (restated in condensed form in
ADR-0010 → Routing matrix),
and SHALL NOT be duplicated here.
A reviewer comment that lists multiple findings SHALL tag each finding individually:
**Finding 1 (v1-F1)**
class: tech
<one-paragraph description and remediation pointer>
**Finding 2 (v1-F2)**
class: arch
<one-paragraph description and remediation pointer>
Findings without a class: tag are malformed and SHALL be returned
to the reviewer for retagging before the routing engine consumes
them.
Append-only revisions
Once a plan comment is validated (by the reviewer in autonomous
modes or by the user in FULL / INTERMEDIATE mode), it SHALL NOT
be edited or deleted (R9). Subsequent revisions are posted as new
comments with the revision header above, citing the trigger.
Silent edits of a validated plan break the audit trail the
retroactive review loop relies on and are prohibited.
Worked example
The first live use of the PLAN stage was the validated plan for
issue #170 (the spec-PR workflow ticket), authored by the
architect role in INTERMEDIATE mode and validated by the user
before the implementation branch was cut. It is the canonical
worked example this document points to (R10):
Readers should treat the comment's structure — five mandatory
sections, file-path-anchored steps, an explicit deferral
recommendation, zero [P] markers because the steps were
genuinely sequential — as the lived demonstration of the schema
above.