Spec NNN — [Feature name]

Status: draft Branch: NNN-[slug]

Status is set by the human, never by the agent. It moves draft → approved → implemented.

Problem

[What's wrong or missing today, in one short paragraph. No solution here.]

User stories

Ordered by priority. Each story must be independently testable and shippable — if only P1 ships, there is still something usable.

P1 — [title]

As a [player / seller], I want [capability] so that [outcome].

Independent test: [how this story is verified on its own, with no other story implemented.]

Acceptance scenarios

1. Given [state], when [action], then [observable result].
2. Given [state], when [action], then [observable result].

P2 — [title]

[same shape]

Requirements

• R1 — [a single, testable requirement.]
• R2 — [...]

Mark anything unresolved inline rather than assuming an answer. Two markers, split by who can answer:

• [NEEDS CLARIFICATION: specific question] — only the human can answer. A product decision, a scope boundary, a preference. Blocks step 1.5.
• [NEEDS VERIFICATION: specific question] — only reality can answer. Whether the codebase works that way, whether an endpoint returns that field, whether that number is achievable. Answered in research.md with cited evidence, never by assumption. Blocks the approval gate.

Any success criterion stating a number carries a [NEEDS VERIFICATION] until a measurement in research.md backs it. An unbacked number is a guess wearing a criterion's clothes.

Success criteria

Measurable and technology-agnostic — outcomes, not implementation.

• SC1 — [e.g. "all 19 Gen 1 legendaries are ranked in under 2 s on a warm cache"]
• SC2 — [...]

Out of scope

• [explicitly excluded, so it doesn't creep back in]

Assumptions

• [scope boundaries, prerequisites, data or system dependencies taken as given]

Traceability

Each acceptance scenario and success criterion must map to a named test. Fill this in during implementation.

Criterion	Test
P1 #1
SC1