Spec

spec: as much process as the change deserves, and no more

1. Pick the tier: argue it, don't default upward

• S: no spec. Small, clear, reversible: bugfix, copy change, config tweak, single-file change with obvious behavior. The commit message and a test are the record. If you're explaining the tier choice in more than a sentence, it isn't S.
• M: spec.md only. A feature or change in one area, buildable in a session or two.
• L: spec.md + plan.md. Multi-session, multi-area, risky, or contested. Copy docs/specs/TEMPLATE-PLAN.md to plan.md: build order (owned by the ticket graph), seams/interfaces touched, migration/rollback, verification approach.

Two honest tests: Would a senior write this down first? and Will anyone need to know why in three months? Yes to either → at least M.

2. Tier M and L: interview before writing

Build shared understanding first; a finished draft the owner can only react to is not that. Tier S is exempt: a bugfix gets no interview. The rules:

• One question at a time. Each question comes with your recommended answer and a one-line reason, so the owner can accept the default or push back cheaply.
• Recommendations are argued, not agreeable. A question with a real design choice behind it gets the critical-thinking moves first: the recommendation names the alternative it beat.
• Facts are looked up, never asked. Whatever the repo, the docs, or the code can answer, you answer yourself before asking anything.
• Decisions are put to the owner, never assumed. Scope, trade-offs, and preferences are the owner's; surface each one as a question, however obvious the answer seems.
• Pin fuzzy terms as they surface. A word with two possible meanings goes into the glossary docs/product/CONTEXT.md right then, so the spec uses one word for one thing.
• Write only after confirmation. Close the interview by playing back your understanding in a few lines and asking the owner to confirm it. Only then start writing. Record the confirmation (date plus the owner's words) in the spec's sign-off line; it replaces a bare "approved".

3. Write it

Copy docs/specs/TEMPLATE.md to docs/specs/<NNN>-<slug>/spec.md (NNN = next number). The parts that matter most:

• Traces to a BRIEF SC-item or an explicit request: no trace, no build (run scope first).
• Acceptance criteria: numbered, testable, phrased as observable behavior. These become the verification checklist; write them so verify can execute them without interpretation.
• Not in this change: the adjacent work you are deliberately not doing. This line is what keeps "while I'm here" out of the diff.
• Settled decisions: choices made during the interview, each with its one-line reason. Later sessions build on these instead of re-opening them; only the owner re-opens a settled decision. This section is what stops a fresh context from re-litigating the design.

4. Tier L (and multi-session M): cut tickets

When the work will not fit one session, decompose the spec into tickets before building. Copy docs/specs/TEMPLATE-TICKET.md to tickets/<NN>-<slug>.md inside the spec folder, one file per slice, numbered in rough build order.

• The first ticket is a tracer bullet. The thinnest end-to-end slice that touches every layer involved and proves the shape works, verified before anything widens. Later tickets expand from it; never build broad before one narrow path runs for real.
• Slice vertically. Each ticket cuts a narrow but complete path through every layer involved and is demoable or verifiable on its own. Never one layer per ticket.
• Size to one fresh agent session. Too big to finish with context to spare? Split it.
• Declare edges. Blocked by: names the sibling tickets that must be done first; the ticket graph owns the build order.
• Build on the frontier. Work the lowest-numbered ticket whose blockers are all done, one ticket per fresh session, clear context between tickets (hand back with the literal command and paste-ready resume prompt from checkpoint's hand-back format). STATE.md Now ▶ points at the frontier ticket. Statuses: ready | building | done.

5. Sign-off and build

M and L need owner sign-off before building starts. The sign-off is the interview's shared-understanding confirmation, recorded in the spec header; if the written spec drifted from what was confirmed, go back to the owner before building. Set spec status building, note it in STATE.md, build one criterion at a time (one ticket at a time when the spec has tickets).

6. Converge when it ships

On done (with verify green and code-review clean or recorded as skipped for the trivial tier - verify §4 routes this): status done with Verified by: naming the artifact verify produced; reconcile every doc the change made stale: update the owning file, add retired wording to the denylist in checks/config.json; move the folder to docs/specs/archive/. A spec that contradicts shipped reality is worse than no spec. ⚓