Product Spec

Reply in the project conversation language (CLAUDE.md → Language); code, identifiers, paths and commit messages stay in English.

Template: .claude/docs/templates/product-spec.md (sections 1–10). Section by section: questions → section draft → edits → next. The file is written once at the end (or per section, the user's choice), always after "May I write?". In the commands below, <hooks> is .claude/hooks/ in copy mode and ${CLAUDE_PLUGIN_ROOT}/hooks/ in plugin mode.

Phase 1: Context

1. Read docs/specs/concept-brief.md (if any), technical-preferences.md, production/roadmap.md and production/stage.txt.
2. Stack. When the stack is not configured, suggest /setup-stack before or after this skill (not blocking).
3. No clear product. When there is no concept brief and the user cannot say what the product is and for whom, stop before any section: suggest /brainstorm and write nothing.
4. Pick the mode.
   • Retrofit mode — stage build or later, with code and a deployment that already exist. The spec documents what runs, not what is planned. Sources are CLAUDE.md, the roadmap, the deployed configuration and the code. Phase 2 becomes one pass: draft all sections from those sources, show the draft as a whole, and ask questions only where the facts are silent (goals, audience, out-of-scope). The Phase 3 review verifies claims against the repository: a claimed fact the repository contradicts is BLOCKING.
   • New spec — every other case: Phase 2 as written.

Phase 2: Sections 1–10

For each section, in template order:

1. Ask 1–3 AskUserQuestions.
2. Draft the section and ask "like this?"; apply the edits.
3. Section-specific rules:
   • §4 Scope: insist on In / Later / Out. Every Out item has a reason; a feature the user places out of scope is recorded under Out with that reason, never dropped.
   • §6 Non-functional requirements: propose the studio defaults (CWV, WCAG 2.2 AA, OWASP baseline); the user confirms. §6 always answers localisation, SEO and product analytics explicitly — n/a — reason is an answer, silence is not. Analytics events map to the §2 metrics when there are any.

Phase 3: Review

1. Mode: --review, else production/review-mode.txt, else lean.
   • full: technical-director (feasibility, stack risks) and security-lead (data, jurisdiction) in parallel via Task, each with a verdict PASS/CONCERNS/FAIL and reasons.
   • lean: technical-director only if there are non-trivial NFRs or integrations.
   • solo: no review.
2. CONCERNS/FAIL: show the findings and propose edits. Never advance the stage automatically.
3. Re-review the edits. The edits go back to the same verifier (same contract, a short answer to one question: "do the findings still stand?"). The document's verdict is the verdict of the last review, not the first one with a list of fixes claimed against it: a spec rewritten "according to all eight comments" has been checked by nobody. When the user chooses to skip the second review, say so plainly and record the verdict as FAIL (edits unverified).
4. The skill verdict follows the last review's. PASS → APPROVED. CONCERNS → APPROVED with the concerns listed in the verdict line, or NEEDS REVISION when a concern is on §1–3 (goals, users, scope — a concern there changes what every later section is about). FAIL, including FAIL (edits unverified), → NEEDS REVISION, the qualifier carried over. No review ran (solo, or lean with nothing to review) → APPROVED, and the verdict line says "no review".
5. Open items reach production/findings.md. For every BLOCKING and HIGH item of the verdict, one AskUserQuestion: record it in production/findings.md (template findings.md; id ARCH-NNN, severity, area/feature, the decision needed) (Recommended) · story stubs — through /feature-spec F-NNN for the first feature the item touches (a hand-off: this skill does not run it; the stories come from /create-stories once that spec has acceptance criteria, and /create-stories blocks without a feature spec with criteria — the closing question names /feature-spec F-NNN when this option was chosen) · keep it in the spec only. Write the row only after the "record" answer; that answer is the write consent, so touch .claude/.write-consent first (rule 7). Record the gate before asking — <hooks>session-state.sh set Gate "/product-spec Phase 3: record ARCH-NNN?" — and clear it after the answer (<hooks>session-state.sh set Gate "—"). A BLOCKING that is neither recorded nor turned into a story is named as such in the verdict line: /create-stories, /sprint-plan and /help read production/findings.md, and nobody reads §8 of the spec for open decisions.

Phase 4: Write

1. Render the draft (or the diff) in the chat.
2. "May I write docs/specs/product-spec.md?" — one AskUserQuestion: write (Recommended) · show the draft/diff first · not now.
3. After the "write" answer: touch .claude/.write-consent (rule 7 — the consent-guard hook checks the marker), then write.
4. Stage. Propose production/stage.txt = specification only when the current stage is earlier than specification in the catalog. On a project already in build/operate the stage is never proposed backwards.

Phase 5: Commit (documents lane)

Right after the write, one commit gate (rule 7 (4), .claude/docs/git-workflow.md § Documents): one AskUserQuestion offering docs: product spec, staging exactly the written files — docs/specs/product-spec.md, the production/findings.md rows recorded in Phase 3 and production/stage.txt when it changed; a spec written per section gets one gate, after the last section. Record the gate before asking — <hooks>session-state.sh set Gate "/product-spec Phase 5: commit?" — and clear it after the answer (<hooks>session-state.sh set Gate "—").

• On the default branch when no story work is in progress.
• When HEAD is a story branch, name it and offer: switch to the default branch and commit there (Recommended — a pipeline-wide document) · commit here (the document belongs to this story) · leave uncommitted.
• Code, configs, workflows and scripts never ride the docs: commit.

Nothing is committed without the answer.

Verdict: APPROVED | NEEDS REVISION. Next step — one AskUserQuestion: /feature-spec for the Must features (Recommended) · /game-concept (game) · revise the spec. When Phase 3 step 5 chose story stubs for an item, the first option reads /feature-spec F-NNN for that feature (Recommended) and says that /create-stories follows once the spec has acceptance criteria — it blocks without them.