spec

Spec

Shape an idea, vague ticket, or open product question into a lightweight product spec. This is the product/requirements gate, not the implementation-design gate.

Use this for:

• Open-ended brainstorming
• Vague tickets that are not ready for implementation design
• Product behavior, scope, and acceptance criteria discovery
• Writing a lightweight spec/PRD before blueprint

Do not use this for:

• Implementation design when the requirement is already clear — use blueprint
• Breaking an approved spec into implementation phases — use break-spec
• Writing code or scaffolding

Do NOT design implementation details, invoke `implement`, write code, or scaffold until the product behavior and scope are approved or the user explicitly routes to `blueprint`.

You may skip steps if the current conversation or kickoff already supplied enough context.

Step 1: Load context

Collect any supplied context:

• User idea or prompt
• Ticket title/body/comments
• Codebase findings from kickoff, if provided
• Existing plans/specs in plans/
• Relevant docs or recent commits

If working inside a repo, do light codebase exploration before asking detailed questions. Search for existing patterns, data models, API boundaries, and test coverage that affect the product decision. Record facts, not opinions.

Step 2: Identify unknowns

Write down 5–10 targeted questions about what you do not know. Frame them as questions, not statements. Focus on:

• The problem and who feels it
• Desired behavior
• Success criteria
• Scope boundaries
• Constraints and risks
• Product decisions that block implementation design

Step 3: Interview the user

Ask questions one at a time. Prefer multiple choice when possible. If a question can be answered by the codebase or supplied ticket context, answer it from evidence instead of asking.

For each unresolved question, present:

• What the codebase/ticket suggests
• Your recommended answer
• What decision remains for the user

Step 4: Propose product directions

When there are multiple plausible interpretations or solutions, propose 2–3 product directions with trade-offs and your recommendation. Keep this at the product behavior level. Do not choose file-level implementation details here.

If the requirement is already obvious and only minor details were clarified, this can be a short paragraph.

Step 5: Present the spec for approval

Before writing an artifact, present the proposed spec in concise sections and ask for approval or corrections:

• Problem statement
• Current state
• Desired state
• User stories / acceptance outcomes
• Key decisions
• Out of scope

Do not proceed until the user approves the product direction.

Step 6: Write the spec

Use this template. Do NOT include exact file paths or code snippets unless the user explicitly wants an implementation-adjacent note; those belong in blueprint.

# [Feature Name]

Problem Statement

What's broken or missing. Who it affects.

Current State

How things work today. What patterns exist.

Desired State

What the world looks like after this ships.

User Stories

• As a [role], I want [thing] so that [outcome]

Key Decisions

Decisions already resolved during the interview, with rationale.

Out of Scope

What this spec explicitly does not cover.

Step 7: Output and route

Ask the user: "Should this go to your issue tracker as a document, or stay local?"

• Tracker: if an issue-tracker tool is connected, create a document or issue there and link it to the relevant project
• Local: write to plans/<feature-name>-spec.md

Then route:

• If the spec is too large for one coherent PR, hand off to break-spec
• If the spec is implementation-ready and scoped, hand off to blueprint
• If invoked by kickoff, return the approved spec and routing recommendation to kickoff