Spec

---
name: spec
description: Use when starting a new project, feature, or significant change — writes a spec/PRD covering objectives, structure, commands, code style, testing, and boundaries before any code. Triggers on "write spec", "create prd", "spec out", "写需求文档", "写规格", "需求文档" — also when user says "要做什么" / "需求是什么".
---

# Spec

Write a structured specification before any code. The spec is the shared source of truth —
it defines what we're building, why, and how we'll know it's done. Code without a spec is
guessing.

## When to use

- Starting a new project, feature, or significant change.
- Requirements are ambiguous or only exist as a vague idea.
- The change touches multiple files or modules.
- User says "write spec", "create prd", "spec out", "to spec", "写需求文档", "写规格", or "需求文档".

**Not for:** single-line fixes, typos, or changes where requirements are unambiguous; changes needing design decisions only — use `architecture` for system design.

## Steps

1. **Surface assumptions.** Before writing any spec content, list what you're assuming
   (tech stack, auth model, database, target environment). Ask the user to correct before
   proceeding. Don't silently fill ambiguous requirements.

2. **Ask 3–5 clarifying questions** where the prompt is ambiguous — problem/goal, core
   functionality, scope, success criteria. Offer lettered options (A/B/C/D) so the user
   can respond "1A, 2C, 3B" for quick iteration. Only ask what's actually ambiguous. If the
   conversation already resolved the ambiguities, skip questions and synthesize directly.

3. **Write the spec** using the template below. Reframe vague requirements as testable
   success criteria ("make the dashboard faster" → "LCP < 2.5s on 4G; initial load < 500ms").
   For PRD structure, user-story format, Given/When/Then acceptance criteria, and INVEST —
   load `references/prd-patterns.md`. For success-criteria frameworks (North Star, AARRR,
   retention, A/B testing) — load `references/metrics-frameworks.md`. For feature
   prioritization (RICE, Kano, MoSCoW) — load `references/prioritization.md`.

4. **Publish.** Two layers:
   - `docs/PRD.md` — project-level requirements, concise (mermaid-heavy), on main. The shared
     source of truth for the whole project.
   - `docs/vX.Y/prd.md` — the current version's detailed PRD (user stories, full acceptance
     criteria, rules, boundaries), on the version branch. Falls back to `docs/PRD.md` alone for
     single-version projects.
   Commit both — they are living documents. Update when decisions or scope change; reference in PRs.

5. **User review gate.** Ask the user to review the written spec before any implementation.
   If they request changes, make them and re-verify. Only proceed once approved.

**Spec template:**

```markdown
# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories with verifiable acceptance criteria.]

## Success Criteria
[Project-level "how we know it's done" metrics.]

## Project Structure
[Directory layout with descriptions — where source, tests, docs live.]

## Commands
[Build, test, lint, dev — full executable commands with flags.]

## Code Style
[One real code snippet showing conventions. Naming, formatting, key patterns.]

## Testing Strategy
[Framework, test locations, coverage expectations, which test levels for which concerns.]
Identify test seams — prefer existing seams, use the highest seam possible (the fewer seams across the codebase, the better).

## Boundaries
- Always: [run tests before commits, validate inputs, follow naming conventions]
- Ask first: [schema changes, new dependencies, CI config changes]
- Never: [commit secrets, edit vendor dirs, remove failing tests without approval]

## Non-Goals
[What this feature will NOT include. Makes scope trade-offs explicit.]

## Open Questions
[Unresolved items needing human input.]
```

Planning the implementation FROM this spec uses Claude Code's built-in plan mode
(see engineering-principles §7) — no custom plan skill. The spec is plan mode's input.

## Verify

- The spec file exists on disk and is committed to version control.
- It covers all sections: Objective, Success Criteria, Structure, Commands, Code Style, Testing, Boundaries, Non-Goals.
- Success criteria are specific and testable, not vague.
- Boundaries (Always / Ask first / Never) are defined.
- The user has reviewed and approved the spec.

**Output:** `docs/PRD.md` (project-level, concise, main) + `docs/vX.Y/prd.md` (version-level, detailed, version branch). Single-version projects fall back to `docs/PRD.md` alone.

## References

- [${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md](${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md) — discipline shared by every skill; §7 covers plan mode for implementation planning.
- [${CLAUDE_PLUGIN_ROOT}/references/product-principles.md](${CLAUDE_PLUGIN_ROOT}/references/product-principles.md) — product discipline (need≠feature, outcomes over outputs, say no to good ideas, the real competitor is the workaround).
- [references/prd-patterns.md](references/prd-patterns.md) — PRD structure, user stories, Given/When/Then acceptance criteria, INVEST, Non-Goals, success-criteria reframing, anti-patterns.
- [references/prioritization.md](references/prioritization.md) — RICE, ICE, Kano, MoSCoW, Value×Feasibility matrix, true-need vs false-need filter.
- [references/metrics-frameworks.md](references/metrics-frameworks.md) — North Star metric, AARRR funnel, retention curves, cohort analysis, Hook Model, A/B testing discipline, data-driven loop.