Playbook: Add a Feature

Objective

Ship one feature as a verified vertical change: committed spec, approved plan, constrained implementation, green gates with evidence, and human-checked acceptance — without drive-by refactors or silent product decisions.

When to use

Rails exist (CLAUDE.md, quality gates). The feature is bounded enough to name in one sentence. If the idea is still fuzzy, run Idea to Spec first. If the change is "rewrite this subsystem," use Legacy Refactor or Large Tasks instead.

Inputs required

• One-sentence goal and who cares.
• Pointers to related code / prior specs (paths).
• Non-negotiable constraints (compat, perf budget, security).
• Definition of done you can execute (curl, UI click, SQL check) — not "looks good."

Step-by-step process

1. Spec before code

If no spec exists, create one (template: Specs and Planning):

Draft specs/<nnn>-<feature-slug>.md for: <one-sentence goal>.

Sections required: Goal, Non-goals, Acceptance criteria (testable),
Constraints, Out of scope, Open questions.
Infer constraints from CLAUDE.md and ARCHITECTURE.md.
Do not write application code. Stop when the draft is ready for my edit.

You edit acceptance criteria personally. Weak criteria ("fast", "secure", "intuitive") are not done definitions.

2. Questions-first pass

Read specs/<nnn>-<feature-slug>.md and CLAUDE.md.
List every undecided decision that would affect implementation.
For each: options, your recommended default, risk if wrong.
Do not implement. Stop after the question list.

Answer in the spec (not only in chat) so the next session inherits them. Control pattern: Control Techniques.

3. Plan mode with file allowlist

Plan implementation of specs/<nnn>-<feature-slug>.md.

Plan must include:
- File allowlist (and explicit do-not-touch)
- Sequence of increments with a verification command each
- Risks (data migration, API compat, authz)
- Test strategy (what new tests, what existing tests must stay green)

Plan mode: no edits until I approve. If >~8 steps, propose PR splits.

Reject plans that add speculative layers, new dependencies without asking, or "cleanup" outside the feature.

4. Implement one approved increment at a time

Implement increment <k> only from the approved plan for
specs/<nnn>-<feature-slug>.md.

Stop-and-ask: any decision not in the spec or CLAUDE.md → BLOCKER.
Stay inside the allowlist; if blocked, propose allowlist amendment.

When done: paste `make check` output and the manual verification steps
for this increment. Do not start increment <k+1>.

Fresh session per large increment if the prior session thrashed.

5. Human acceptance before merge

Run the acceptance criteria yourself. Agent-claimed "done" is a candidate, not a ship decision. Then open the PR with spec sync (Keeping Specs Alive) and Reviewing AI PRs.

Human review points

1. Spec acceptance criteria — you wrote/edited them.
2. Answers to open questions — recorded in the spec.
3. Plan approval — especially allowlist and dependency asks.
4. Manual acceptance — you executed the checks.
5. PR pass 1–3 — intent, boundaries, evidence.

Expected artifacts

specs/<nnn>-*.md (accurate) · approved plan (in session or specs/.../plan.md if you keep them) · scoped diff · new/updated tests · pasted gate output · PR with spec sync checklist.

Common failures

Symptom	Root cause	Early detection	Fix
Feature works demoware, fails edge case in spec	Shallow implementation; acceptance not run	Manual acceptance skipped	Fail PR; add failing test from the missed criterion; re-run
15-file refactor inside "add filter"	No allowlist / weak plan	Diff file count vs plan	Revert drive-bys; re-implement with scope
Silent product choice (e.g. 403 vs 404)	No stop-and-ask	Review status codes / error shapes	Amend spec; align code
Spec unchanged, behavior changed	No sync checklist	Pass 1 review	Update spec in same PR or revert behavior
Session invents a second helper	Poor navigability	Duplicate symbols in diff	Extend existing module; see Navigability

Recovery strategy

Wrong direction mid-feature: stop, context reset, amend spec, new plan — do not "prompt harder" on a polluted session. Catastrophic diff: see Recovery. Partial good work: keep green increments on a branch; revert the bad increment only.

Acceptance criteria

• [ ] Spec acceptance criteria are testable and human-verified
• [ ] Diff matches plan allowlist (or documented amendments)
• [ ] make check green with evidence pasted in PR/session
• [ ] Spec updated in the same PR if behavior changed
• [ ] No new dependency without explicit human approval
• [ ] Non-goals respected (no silent scope expansion)

Related

• Idea to Spec — when the feature isn't crisp yet.
• MVP Build — multi-slice delivery on a new product.
• Control Techniques — questions-first, scope, evidence.
• Writing Effective Specs — spec quality bar.
• Reviewing AI PRs — merge gate.
• Large Tasks — when one feature exceeds a reliable session.