Requirements gathering

Requirements Gathering Skill

<!-- CANONICAL SOURCES: - CLAUDE.md Canonical Paths - docs/ENTRYPOINTS.md - Epic #901 (User Advocate Pipeline) -->

Process

Phase 1: Analyze the Request

1. Parse the user's raw input for intent, scope, and stakeholders
2. Identify ambiguities — what's unclear or underspecified?
3. Classify the request type: feature, improvement, fix, research, infrastructure
4. Assess complexity: simple (1-2 steps), moderate (3-5), complex (6+)

Phase 2: Extract Requirements

Structure findings as:

Functional Requirements — What the system must do Non-functional Requirements — Performance, security, usability constraints Constraints — Technical limitations, timeline, dependencies

Phase 3: Map to Capabilities

Cross-reference requirements against available nexus-agents capabilities:

Capability Type	Where to Check
MCP Tools (20)	CLAUDE.md MCP Tools Reference table
Workflows (9)	src/orchestration/graph/templates/
Expert Roles (9)	src/agents/experts/expert-config.ts
CLI Adapters	src/cli-adapters/factory.ts
Security Pipeline	src/security/

Phase 4: Identify Gaps

For each requirement that cannot be fulfilled:

• Describe the gap clearly
• Suggest workarounds using existing capabilities
• Flag for issue creation if the gap is significant

Phase 5: Generate User Stories

Format each requirement as a user story:

As a [role], I want [capability] so that [benefit]

Acceptance Criteria:
- Given [context], When [action], Then [outcome]
- Given [context], When [action], Then [outcome]

Priority: P1/P2/P3/P4
Dependencies: [list]

Phase 6: Propose Plan

Summarize the implementation approach:

1. Which existing tools/workflows/experts to use
2. What new capabilities need to be built
3. Suggested phasing (what to build first)
4. Risk assessment

Output Format

## Requirements Analysis

### Intent

[1-2 sentence summary of what the user wants]

### User Stories

1. **[Story Title]**
   As a [role], I want [capability] so that [benefit]
   - AC: [acceptance criteria]
   - Priority: [P1-P4]

### Capability Mapping

| Requirement | Available Tool/Workflow | Status          |
| ----------- | ----------------------- | --------------- |
| [req]       | [tool/workflow/expert]  | [available/gap] |

### Gaps Identified

- [Gap description + suggested workaround]

### Recommended Approach

[Phased implementation plan using existing capabilities]

When to Use

• User describes a feature vaguely ("make it do X")
• Planning a new epic or large feature
• Evaluating whether a request is feasible with current capabilities
• Bridging between user intent and technical implementation

Divergent → Convergent thinking

For ambiguous or open-ended requests, run a structured ideation pass before settling on requirements:

Step 1 — Diverge

Restate the idea in your own words, then ask three sharpening questions:

1. What problem does this actually solve? Often the request describes a solution, not the problem.
2. Who is harmed if we don't do this? Identifies the real stakeholder.
3. What would success look like at the end of the first hour of use? Concretizes the acceptance criterion.

Then generate 2-3 variations of the request — different scopes, different users, different mechanisms.

Step 2 — Converge

For each variation:

• Cluster — what assumptions does this share with the others?
• Stress-test — what's the failure mode? What if the assumption is wrong?
• Surface hidden constraints — what is the user assuming we already know? (Tech stack, deadlines, audience, success metrics)

Step 3 — Sharpen and ship

Produce a one-pager with: Problem statement, Recommended direction, Key assumptions, MVP scope, Not Doing list. The Not Doing list is the highest-value section — it makes scope decisions explicit.

Dependency-graph identification

When the request becomes a multi-task plan, map dependencies before sequencing:

1. List the tasks.
2. For each task, identify what must exist before it can run (schemas, APIs, data, other modules, tests, docs).
3. Identify parallel-safe tasks — those with no shared dependencies.
4. Identify serial bottlenecks — single tasks that block many downstream items.

Sequence: serial bottlenecks first, then parallel-safe waves of 3-4 (per .rules/subagent-coordination.md), then late-stage integration tasks.

Anti-rationalization — Requirements

Excuse	Counter
"The user said X, so we build X"	Users describe solutions; you need the problem. Restate, ask the three sharpening questions.
"This is obvious, no need to write it down"	Obvious to whom? Different stakeholders read "obvious" differently. The Not Doing list catches the silent disagreements.
"We can figure out scope as we go"	Scope creep is the most expensive bug. Lock the MVP and the Not Doing list before writing code.
"The acceptance criterion is 'when it works'"	"Works" is unfalsifiable. The criterion is a test or a user scenario the spec can be measured against.
"We don't need to identify dependencies, we'll just hit them"	Hitting dependencies serial costs ~Nx the time vs identified-and-parallelized. Map first, then sequence.

Red flags

• Requirements doc with no "Not Doing" list
• User stories without testable acceptance criteria ("works", "is fast", "looks good")
• Capability mapping skipped — gaps not flagged
• Dependencies not listed; serial bottlenecks unidentified
• Spec produced without surfacing assumptions explicitly

Verification checklist

• Three sharpening questions asked + answered in the spec
• At least 2-3 variations explored before converging
• "Not Doing" list explicit and signed off
• User stories have testable acceptance criteria
• Capabilities mapped to existing tools/workflows; gaps flagged
• Dependency graph identified; parallel-safe vs serial labelled