Requirement Gathering

Structured interview process that turns vague requests into clear, actionable requirements, before openspec-propose / openspec-explore generate any artifact and before spec-writer writes anything.

When to use

• A new task arrives from a stakeholder (feature, bugfix, refactor) and the request is ambiguous or missing acceptance criteria.
• Existing capability specs in openspec/specs/ don't cover the requested change, or only partially cover it.
• Before running openspec-propose, openspec-explore, or spec-writer.

Rules

• Ask ONE question at a time. Wait for the answer before asking the next one.
• Never begin implementation, never run openspec-propose, never write a spec until requirements are confirmed.
• Base questions on gaps found in existing specs, not on assumptions.

Inputs

• The stakeholder's initial request.
• Existing capability specs under openspec/specs/<capability>/spec.md (if any).

Steps

1. Review existing specs. Scan openspec/specs/ for capabilities related to the request:

   find openspec/specs -mindepth 2 -maxdepth 2 -name spec.md

   For each match, read its ## Purpose and ### Requirement: sections. Note what's already documented and what's missing.

2. Identify gaps. List the ambiguous or underspecified areas:

   • Unclear scope boundaries (what's in vs. out)
   • Missing edge cases or error handling expectations
   • Unspecified behavior for boundary conditions
   • Unclear integration points with existing capabilities
   • Missing non-functional requirements (performance, security)
   • For modified capabilities: which existing ### Requirement: blocks actually change behavior (spec-level), vs. which are just implementation detail (not spec-level)

3. Interview the stakeholder. Ask ONE question at a time. Wait for the answer before asking the next. Prioritize by impact — scope and core behavior first, edge cases second.

   Good questions are specific and bounded:

   • "Should the API return a 404 or an empty list when no results match?"
   • "Is this endpoint authenticated, and if so, which roles have access?"
   • "Which source files will this capability own (targets:), or does it modify an existing capability's targets?"

   Bad questions are open-ended or bundled:

   • "What should the API do?" (too vague)
   • "What about errors, pagination, auth, and rate limits?" (too many at once)

4. Summarize requirements. After all questions are answered, present a concise summary back to the stakeholder for confirmation.

5. Get explicit approval. Do not proceed until the stakeholder confirms the summary is accurate. If they correct anything, update the summary and re-confirm.

Output

A confirmed requirements summary, ready to be handed to openspec-propose (or openspec-explore if still investigating approaches) and, once specs are drafted, to spec-writer. The summary should include:

• Scope: what's included and excluded.
• Core behavior: the happy path.
• Edge cases: boundary conditions and error handling.
• Constraints: performance, security, compatibility requirements.
• Capabilities touched: new capability names (kebab-case, will become openspec/specs/<name>/spec.md) or existing capability names whose requirements change.
• Verification expectations: for each core requirement identified, a rough idea of what would verify it (feeds the **Verified by**: [@test] ... line spec-writer will add later).

Success criteria

• Zero ambiguous requirements remain after the interview.
• Stakeholder explicitly confirmed the summary.
• No implementation work, and no openspec new change / openspec-propose run, began before confirmation.