feature-planning

feature-planning skill

This skill maintains the specs/ directory — one markdown file per feature, each a living document that evolves with the feature it describes. Specs sit between PROJECT_CONSTITUTION.md (durable principles) and the code (implementation): they capture what a feature is, why it exists, what's in/out of scope, and what's been decided.

The skill does five things, depending on the user's intent:

1. Create a new spec when one doesn't exist.
2. Update an existing spec — typically appending a decision or shifting status as work progresses.
3. Report status when the user asks what's in flight or what's been shipped.
4. Implement against a spec — read it before changing code, update it when implementation reveals new decisions.
5. Review on demand — re-run the spec-reviewer sub-agent against an existing spec to surface gaps the user wants checked.

New specs (Mode 1) and substantive edits to existing specs (Mode 2) are also automatically run through the review pass documented below — a sub-agent that checks for completeness, accuracy against the constitution, and ambiguity, and surfaces clarifying questions.

Specs are not plans. Plans (under ~/.claude/plans/) are per-conversation scratch space. Specs are project artifacts, checked in, intended to outlive many conversations.

File layout

study-help/
├── specs/
│   ├── README.md           ← index, one row per spec
│   ├── highlights.md
│   ├── notes.md
│   └── auth-sessions.md
└── .claude/skills/feature-planning/
    ├── SKILL.md            ← this file
    └── references/
        └── spec-template.md

Naming. Spec files use kebab-case slugs (highlights.md, auth-sessions.md, passage-reader.md). No date prefix, no number prefix — slugs are stable identifiers, easy to link by name. Sort alphabetically.

Mode 1 — Create a new spec

Trigger: user says "plan a feature", "draft a spec for X", "spec out X", or runs /plan-feature [name]. The feature does not yet have a file in specs/.

Steps

1. Confirm the slug. Derive a kebab-case slug from the feature name. If it's ambiguous (e.g. user says "spec out the reader" — could be reader.md or passage-reader.md), ask before proceeding. Slugs are stable; renaming later is friction.

2. Check it doesn't already exist. ls specs/ (or read specs/README.md). If the slug exists, switch to Mode 2 (Update) and tell the user.

3. Read the constitution. Open PROJECT_CONSTITUTION.md and identify which sections this feature relates to (in-scope items in §2, principles in §3, guardrails in §4, non-goals in §5). The spec must reference real section numbers — don't invent links.

4. Copy the template. Read references/spec-template.md and write it to specs/<slug>.md with these fields filled in:

   • # <Feature name> — title-case the slug.
   • Status: Draft.
   • Created: today's date in YYYY-MM-DD (use the currentDate from the conversation context, not a guess).
   • Last updated: same as Created.
   • Owner: unassigned unless the user names one.
   • Why: one paragraph from what the user told you, plus the constitutional reference. Don't pad it.

5. Leave the rest deliberately incomplete. Goals, Non-goals, User-facing behavior, Implementation outline, Open questions, Verification — these should have placeholder bullets the user fills in over time. The spec is meant to be iterated, not finished in one pass. Resist the urge to over-specify on day one.

6. Update specs/README.md. Insert a row in alphabetical order: | [<slug>](./<slug>.md) | Draft | <one-line summary> |. If specs/README.md doesn't exist yet, create it from the template at the bottom of this file.

7. Show the draft. Print the path and the rendered spec. Tell the user which sections are still open, and ask which they'd like to fill in first.

8. Run the review pass. See Review pass below. Mode 1 always triggers it — even on a brand-new Draft. Catching constitutional conflicts and underspecified Why paragraphs is cheapest right now.

Mode 2 — Update an existing spec

Trigger: user says "update the X spec", reports a decision ("we're going to store highlights as offsets, not XPath"), or transitions a feature's lifecycle ("highlights is shipped").

Steps

1. Read the current spec first. Always. Targeted edits depend on knowing what's there.

2. Identify which section to touch. Update only that section. Do not rewrite the whole file.

   • Decisions — append a dated bullet: - YYYY-MM-DD: Decided X over Y. Reason: ... Append-only. Never rewrite or reorder past entries.
   • Open questions — when a question is resolved, do not delete it. Move it (or reference it) under Decisions with the resolution. The question's existence is part of the history.
   • Status — only on lifecycle transitions:
     • Draft → In Progress when the first PR for this feature lands.
     • In Progress → Shipped when the feature is user-visible.
     • * → Deprecated when the feature is being removed; add a Decision explaining why. Announce the transition to the user before making it. Don't change status silently. Every transition also triggers a CLAUDE.md sanity check — see Keeping repo docs in sync.
   • Goals / Non-goals / User-facing behavior / Implementation outline / Verification — fine to edit in place as understanding sharpens. Make the edit small and clearly scoped.

3. Bump Last updated: to today's date on every change.

4. Mirror status changes into specs/README.md. If you changed Status, update the corresponding row in the index too.

5. Show what you changed. Print the diff or the relevant section so the user can verify.

6. Run the review pass — only on substantive content edits. If this update touched Goals, Non-goals, User-facing behavior, Implementation outline, or Verification, run the Review pass. Do not run it for:

   • Decisions appends (a decision is, by definition, settled).
   • Open-questions resolutions (the resolution is now in Decisions).
   • Status transitions (Draft → In Progress, etc. — lifecycle, not content).

   This keeps the reviewer out of the way for routine edits while still catching shape changes.

Mode 3 — Status check

Trigger: "what specs do we have", "what's in flight", "what's the status of X".

Steps

1. Read specs/README.md first. It's the index. Don't re-read every spec file unless the user asks for detail on one.

2. Report from the index. Group by status if helpful (Draft / In Progress / Shipped / Deprecated).

3. Check for drift. If the user asks about a specific spec, open it and verify its Status matches the README row. If they disagree, tell the user and offer to reconcile — pick the spec file as the source of truth (the README is a cache).

4. Don't fabricate. If a feature has no spec, say so. Don't invent status from memory or git history.

Mode 4 — Implement against a spec

Trigger: user is doing implementation work on a feature that has a spec (or asks "let's build X" where specs/x.md exists).

Steps

1. Read the spec before changing code. It is the source of intent. Goals tell you what success looks like; Non-goals tell you what to leave out; Decisions tell you what's already been settled.

2. If implementation contradicts the spec, stop. Either:

   • The spec is wrong / out of date → switch to Mode 2, update it, then resume coding.
   • The implementation is wrong → align it with the spec. Do not silently let the code drift from the spec. The spec is the contract.

3. Capture decisions made during implementation. When you make a non-trivial choice while coding (a library, a schema, a tradeoff), append it to the spec's Decisions section before moving on. Otherwise the rationale gets lost between commits.

4. Mark Status: In Progress the first time real code lands for this feature. Mark Status: Shipped when it's user-visible.

5. Refresh CLAUDE.md and STACK.md if they drifted. When code lands, the repo-state snapshot in CLAUDE.md and the tech-choice list in STACK.md may now be wrong. Update them in the same change — see Keeping repo docs in sync.

Mode 5 — Review on demand

Trigger: user says "review the X spec", "check the X spec for gaps", "audit the X spec", or runs /review-spec X. Use this when the user explicitly wants the reviewer re-run against a spec, independent of any edit.

Steps

1. Resolve the slug. If the user gave a name, kebab-case it. Confirm specs/<slug>.md exists by reading the index. If it doesn't, say so — don't create one (that's Mode 1).

2. Run the Review pass. Apply user answers and append logged questions exactly as documented there.

3. Don't change Status. Mode 5 is a quality check, not a lifecycle transition. The only writes are the answer-driven edits and the new bullets under Open questions.

Review pass

This is the shared procedure that Modes 1, 2, and 5 all use. It invokes the spec-reviewer sub-agent and turns its findings into either clarifying questions for the user or new bullets under Open questions.

Steps

1. Invoke the sub-agent. Use the Agent tool with subagent_type: "spec-reviewer". The prompt must contain the absolute paths for:

   • the spec being reviewed (specs/<slug>.md),
   • PROJECT_CONSTITUTION.md,
   • .claude/skills/feature-planning/references/spec-template.md.

   Example prompt body:

   Review the spec at <abs-path>/specs/<slug>.md
   

Content truncated.