{
  "feature": "user-authentication",
  "problem": "Users cannot securely access the application",
  "users": ["end-user", "admin"],
  "scope": {
    "in": [
      "Email/password login",
      "Session management",
      "Password reset flow"
    ],
    "out": [
      "OAuth/social login",
      "Two-factor authentication",
      "Single sign-on"
    ]
  },
  "stories": [
    {
      "id": "US-1",
      "role": "end-user",
      "action": "log in with email and password",
      "benefit": "access my account securely",
      "priority": "must",
      "acceptance": [
        "Given valid credentials, when I submit the login form, then I receive a session token",
        "Given invalid credentials, when I submit the login form, then I see an error message",
        "Given an expired session, when I make a request, then I am redirected to login"
      ]
    }
  ],
  "constraints": [
    "Passwords must be hashed with bcrypt (min 12 rounds)",
    "Sessions expire after 24 hours of inactivity"
  ],
  "dependencies": [
    "User entity must exist before auth service",
    "Email service required for password reset"
  ]
}

Field reference

Field	Type	Description
feature	string	Kebab-case feature name
problem	string	One-sentence problem statement
users	string[]	User roles involved
scope.in	string[]	What's included in this work
scope.out	string[]	What's explicitly excluded
stories	Story[]	User stories with acceptance criteria
stories[].id	string	Story identifier (US-N)
stories[].role	string	User role
stories[].action	string	What the user wants to do
stories[].benefit	string	Why they want to do it
stories[].priority	"must" \| "should" \| "could" \| "wont"	MoSCoW priority
stories[].acceptance	string[]	Given/When/Then acceptance criteria
constraints	string[]	Technical or business constraints
dependencies	string[]	Prerequisites or external dependencies

Step 1: Orient

Before asking a single question, understand where you are.

Read project context — AGENTS.md, README, project docs. Understand the product, tech stack, and domain.
Check existing specs — Scan docs/specs/ for previous work. What features exist? What domain model is established? What patterns and conventions have been set?
Read recent specs — What was the last thing built? Is this new feature building on existing work, extending it, or something greenfield?
Note what you already know — After orienting, you may already have answers to half the discovery questions. Don't ask questions you can answer from context.

This step is silent — don't narrate it. Just read, absorb, and let it inform how much discovery the human actually needs to do.

Step 2: Discovery

Ask questions one at a time. Don't overwhelm with a wall of questions — this is a conversation, not a form. Scale the questioning to the gap between what you learned in orientation and what you still need to know.

Core questions (ask in order, skip what you already know)

What problem are we solving? — Get a concrete problem statement, not a solution description.
Who has this problem? — Identify user roles.
How do they solve it today? — Understand the current workflow and pain points.
What does success look like? — Define measurable outcomes.
What does this integrate with? — Existing systems, data sources, APIs.
What constraints exist? — Technical, business, regulatory, timeline.

If orientation gave you clear answers, confirm rather than ask: "Based on the existing specs, this would integrate with the auth system and the user entity we built last month. Does that sound right?"

Stop when you have enough to define scope.

Step 3: Define Scope

Based on discovery, define clear boundaries.

In scope

Core functionality that delivers the primary value. Critical user journeys. Essential integrations. Must-have business rules. Be specific — "user authentication" is vague, "email/password login with session management" is concrete.

Out of scope

Explicitly list what we are NOT building. This is just as important as what's in scope. It prevents scope creep and sets expectations. Nice-to-haves, future iterations, advanced use cases — name them and defer them.

MVP criteria

What is the minimum that delivers value? What can be learned and iterated on?

Step 4: Extract Stories

Convert discovery into user stories with acceptance criteria.

As a [role]
I want to [action]
So that [benefit]

Each story gets Given/When/Then acceptance criteria. Each story gets a MoSCoW priority: must, should, could, wont.

Decompose large stories into smaller pieces that deliver independent value. Order by dependency and risk — tackle high-risk assumptions early.

Step 5: Write requirements.json

Structure everything into requirements.json:

{
  "feature": "feature-name",
  "problem": "One-sentence problem statement",
  "users": ["role-1", "role-2"],
  "scope": {
    "in": ["Specific capability 1", "Specific capability 2"],
    "out": ["Deferred thing 1", "Deferred thing 2"]
  },
  "stories": [
    {
      "id": "US-1",
      "role": "role-1",
      "action": "what they want to do",
      "benefit": "why they want to do it",
      "priority": "must",
      "acceptance": [
        "Given X, when Y, then Z"
      ]
    }
  ],
  "constraints": ["Technical or business constraints"],
  "dependencies": ["Prerequisites or external dependencies"]
}

Tell the human: "Requirements are drafted. Ready for your review."

STOP. Wait for human review.

Step 6: Iterate

The human may push back on scope, reprioritise stories, add constraints, or cut features. Update requirements.json accordingly. This may take a few rounds.

When the human approves, the requirements are locked for this iteration.

Handoff

When requirements.json is approved, the next step is spec:design.

"Requirements are approved. Ready to research the codebase and design the solution?"

Do not start designing. Do not write code. That's spec:design's job.

spec:product

Spec Product

Artifact

requirements.json Schema