source: .claude/rules/specs.md · generated — edit the markdown, not this file

Spec Lifecycle Rules

Section schema lives in .forge/specs/_TEMPLATE-spec.md. These are the rules for working with specs.

Required Sections

Every spec must have all the following sections populated:

  • Context — why this feature exists, what problem it solves
  • Requirements — what the system must do (functional + non-functional)
  • Acceptance Criteria — how to verify each requirement. For user-facing features with a design reference, include observable visual ACs: name the token / layout / state — e.g. “Type badge uses the semantic tone in the design-system spec”, not “looks good”. A spec classified as a redesign (or otherwise carrying a prototype/mockup) references that artifact in ## Input Sources. Projects with no design reference state functional ACs only.
  • Scope Boundaries — what is explicitly out of scope (both In Scope and Out of Scope listed)
  • Constraints and Dependencies — technical/business constraints, upstream dependencies
  • Open Questions — unresolved questions that must be answered before/during implementation
  • Input Sources — screenshots, flows, reference-system behaviors this spec is based on
  • Revisions — appended after approval when requirements change

Status Transitions

  • New spec → Status: draft in both file and tracker
  • Never assume approval. Only mark approved when the developer explicitly confirms
  • “Looks good” or “that’s fine” → confirm before marking approved: “Should I mark this as approved in the tracker?”
  • Approval requires a Reviewed-via: /forge-spec-review annotation in the header (feature specs only; foundation specs exempt) — the guard-spec-approval hook enforces this at write time
  • At close, tick the acceptance criteria. When the item reaches done (the Reflect walk is the natural moment), every - [ ] under ## Acceptance Criteria becomes - [x], with one dated line at the head of the section pointing at the evidence — the code PRs and the plan’s ## Progress receipts — rather than a pointer per box. An unticked box on a done item reads as an unmet criterion, and nothing else in the file says otherwise. Ticking is an annotation, not a rewrite; a criterion that turned out unmet or retired keeps its [ ] and gains a one-line note in the form — *Not met: <why>; <where that is recorded>.*. python3 .claude/lib/check-done-acs.py fails on a done feature with an unticked criterion that has no *Not met note, or with a criterion joined onto the line before it (a removed note once took the next criterion’s line break with it, hiding that criterion from the check); Repo hygiene runs it on every harness PR and /forge-reflect runs it before the flip to done, because nine features once closed with none ticked. Tick in the delivering PR, not a post-merge follow-up — the ACs reach [x] in the same PR that carries the work that meets them (.claude/rules/tracker.md § Update Rules, “Mark completion in the delivering PR” — which also states the one exception, for ACs owned by a manual wave)

Revision Convention

Approved specs are contracts. When a spec changes after approval:

  1. Add a revision entry at the bottom under ## Revisions
  2. Update the affected requirements and acceptance criteria in the spec body
  3. Note the impact on the plan if one exists

A revision that records the lead’s decision names the lead on its **Approved by:** line (the date is in the ### Rev heading) and asks no one to confirm it on the PR. Where the decision touches other specs still at draft or in-review, add a dated note to each of them in the same PR. A revision that rewords requirements gets the fresh-context comparison of .claude/CLAUDE.md § Compounding Engineering item 6. Why: a confirmation request left in a merged PR is never read, and the team already knows the lead’s decisions (the lead, 2026-10-26).

## Revisions

### Rev 1 — YYYY-MM-DD
- **Changed:** [what changed]
- **Why:** [reason discovered]
- **Impact on plan:** [subtask or approach affected]
- **Approved by:** [name]

Revision required: any change to requirements, acceptance criteria, or scope after approval. No revision needed: typos, clarifying detail that doesn’t change a requirement, open question updates.

Rework Triggers (spec is wrong mid-implementation)

  • Do not silently adjust an approved spec — follow the Revision Convention above
  • If the change invalidates the current plan, pause implementation and revise the plan first
  • Reference-system behavior misunderstood → spec revision
  • Entirely new feature discovered → add to project PRD for decomposition; do not fold into the current ticket

Pre-Spec Gap Check

Before fleshing out any feature spec body beyond ## Context, run the forge-gap-check skill against the spec. Resolve Blockers (B-N) before drafting requirements; Warnings (W-N) can be resolved during drafting or before the plan.

Findings Capture

Tactical findings discovered during/after feature work go in .forge/specs/<feature>-findings.md (use _TEMPLATE-findings.md). The change that creates the file also adds > Findings: [`<stem>-findings.md`](<stem>-findings.md) as the last line of the spec’s header — a link edit, so no revision entry, even on an approved spec; why: nothing else links a findings file, and Repo hygiene fails one that nothing links (“Unreferenced machinery” in python3 .claude/lib/harness-graph.py). One entry per coherent finding, ID format F-NNN, append-only. Promote generalizable findings to .forge/lessons.md during Reflect with a Promoted: L-NNN back-reference; scoped findings stay where they are with Promoted: scoped.

Generated from .claude/rules/specs.md by .claude/lib/render-docs-html.js. Markdown is canonical.