/stdd:spec — Create feature specification

/stdd:spec — Create feature specification

Feature: $ARGUMENTS

Task

Create docs/specs/$ARGUMENTS.md through a guided interview. For every question you ask, propose a recommended answer with a one-line justification grounded in evidence — the user's request, the codebase, prior answers, established conventions, or the spec template. The user accepts, edits, or replaces it; the recommendation is the starting point, not the decision.

If you have no evidence to ground a recommendation, say so and ask the question open-endedly rather than fabricating one. Do not invent unsupported detail just to fill a template section.

Be as detailed as the feature warrants. Include everything an implementor needs to write the code and its tests without guessing.

The spec must be self-contained — see the self-containment rule in the stdd rules. If the user points you at a plan, roadmap, or design doc, read it as an input and inline the contract; do not preserve the pointer.

Before starting

List docs/specs/ and skim for a related file — same domain, same module, similar name. If one looks like the natural home for this feature, surface it:

docs/specs/<found>.md already covers this area. Extend it with new acceptance criteria, or create docs/specs/$ARGUMENTS.md as a separate spec?

If the user picks extend: read the existing spec, run the interview below focused on what's new, then append acceptance criteria using the next free AC-N (the stdd rule keeps IDs stable across edits). Skip "Write this file" — edit the existing spec in place. Confirm with Spec extended at docs/specs/<found>.md and say Run /stdd:tdd <found> to write tests and implement.

If there is no adjacent spec, or the user picks separate, proceed with the new-file flow below.

Questions to ask

For each question below:

• Skip it if the user's request, the codebase, or a prior answer already gives you a confident answer. Don't ask to confirm what you already know — that wastes the user's time.
• Otherwise, ask with a recommendation: state the question, propose a concrete answer, and give a one-line justification (what evidence supports it). Frame it so the user can accept it, refine it, or override it.
• If you have no evidence to ground a recommendation, ask plainly without one — do not fabricate.

A small, well-scoped feature may only need Q1 and Q5. Don't pad to feel thorough.

1. What problem does this solve? Who uses it?
2. What are the inputs and outputs? (types, constraints, examples) Skip if the user's request already names them.
3. What does the public interface look like — function signatures, types, or module shape callers will use? Skip when Q2 already pins this down (e.g. a pure data transform with one obvious signature).
4. What happens normally? What are the edge cases? What errors are possible? Skip when behavior is obviously total — no failure modes worth naming.
5. How do we know it's done? (each criterion independently testable)
6. Of those criteria, which is the smallest end-to-end slice that proves the wiring works — the tracer bullet? Which others matter most if scope must shrink? Skip when Q5 produced ≤2 criteria; the tracer is self-evident.

Write this file

# Spec: $ARGUMENTS

## What
<answer from Q1>

## Inputs / outputs
<answer from Q2>

## Public interface
<answer from Q3>

## Behavior
- Normal: <from Q4>
- Edge cases: <from Q4>
- Errors: <from Q4>

## Acceptance criteria
Order by priority. Each criterion has a stable `AC-N` ID so tests can
reference it. Mark the tracer bullet with `(tracer)`.

- [ ] AC-1 (tracer): <from Q5/Q6 — smallest end-to-end slice>
- [ ] AC-2: <from Q5/Q6>
- [ ] AC-3: <from Q5/Q6>

After writing

1. Confirm: Spec written to docs/specs/$ARGUMENTS.md
2. Say: Run /stdd:tdd $ARGUMENTS to write tests and implement.