analyze-requirements

Skill: Analyze Requirements

Purpose

Diagnose problems at the requirements level and transform vague intentions into valid, testable requirements. Guide developers from "I want to build X" to a clear problem statement, prioritized requirements, explicit constraints, and a bounded scope—all before any design or implementation begins.

Core Objective

Primary Objective: Produce a validated requirements document in which every requirement is testable, clearly scoped, and grounded in a real problem.

Success Criteria(all requirements must be met):

✅ Clear problem: A clear problem statement exists, but does not reference any solution or technology
✅ Requirements testable by ID: Every requirement has acceptance criteria and a unique "R-NN" ID (e.g., R-01, R-02); IDs are sequential, with no gaps or duplicates
✅ Listed constraints: Real constraints (budget, time, skills, dependencies) are separated from assumptions
✅ Bounded scope: The V1 boundary is clear, deferred items are listed, and a trigger for reconsideration is recorded
✅ User confirmation: The user explicitly approves the validated requirements (says "approved," "looks good," "continue," or equivalent)
✅ Document persistence: The requirements document is written to docs/ARTIFACT_NORMS.md according to docs/requirements-planning/<topic>.md and committed

AcceptanceTest: Can someone unfamiliar with the project read the requirements document and understand the problem, who has it, what "done" looks like, and what is out of scope—without asking clarifying questions?

Scope Boundaries

This skill is responsible for：

Vague intent → validated requirements document
Problem discovery and clarification
Clarification needs and writing acceptance criteria
Constraint inventory and assumption mapping
Scope definition and prioritization (V1 vs. later versions)
Requirements quality assessment (clarity, specificity, completeness)

This skill is not responsible for：

Design and architecture decisions (use "Design Solution")
Implementation plans or task lists (use the implementation planning skill)
Code writing (use development skills)
Code review (use "Review Code")
Technology selection (constraints are mentioned, but technology selection belongs to the design phase)

Handoff point: When requirements are validated (all success criteria are met), hand off to "Design Solution" for design exploration, or to implementation planning if the design is trivial.

Use Cases

New project kickoff: A developer says "I want to build X"—extract the real problem and validate requirements before any design.
Feature request triage: A stakeholder submits a vague feature request—clarify the problem, scope, and acceptance criteria.
Scope creep prevention: The project keeps growing—apply prioritization and clear V1 boundaries.
Requirements validation: Existing requirements feel incomplete—diagnose which state they are in and improve them.
Constraint discovery: Mid-project unexpected obstacles — expose hidden constraints and assumptions before they undermine the work.

Behavior (Behavior)

Interaction (Interaction) Policy

Default: Infer the current state from the input; start from the earliest unresolved state
Choose option: One question at a time; provide "[A][B][C]" whenever possible
Confirm: Before exiting the design handoff; before writing the requirements document

Hard gate: no design before verification

DO NOT propose architecture, choose technologies, create designs,
or write code until requirements are validated.

Requirements describe PROBLEMS and NEEDS, not SOLUTIONS.
If a requirement mentions technology, it is a solution in disguise.

Phase 0: Triage

Announce at the start:"I am using the analyzing requirements skill to verify requirements before any design or implementation."

Perform a quick quality assessment of the input:

Dimension	Scope	What to check
Clarity	0–100%	Is there a clear explanation? Are terms defined?
Specificity	0–100%	Is context provided? Are success criteria mentioned? Is scope limited?
Completeness	0–100%	Is all necessary information provided? Are constraints mentioned?

Decision matrix：

Total score	Action
< 40%	Start from state RA0 (problem discovery)
40–70%	Identify the earliest problem state and start from there
> 70%	Quickly verify and focus on gaps

Phase 1: Diagnosis — Determine the current state

Progress through states in order. Do not skip states — if the problem is unclear, do not discuss requirements.

State RA0: No problem statement

Symptoms: Starting from a solution ("I want to build X"); a feature list without a grounded problem; "everyone needs this" reasoning; inability to clearly state who has what problem.

Key questions(ask one at a time):

"What specific frustration or pain point led to this idea?"
"What are people (or you) doing today?"
"What happens if this does not exist? Who suffers and how?"
"If you were the user, what prompted you to think of this right now?"

Interventions：

Problem statement primer: understand who has what problem and why the problem matters
"Five users" test: name 5 specific people who would benefit (even if one of them is you)
Job to be done: "When I [situation], I want [motivation], so that I can [outcome]"
Problem archaeology: trace back to the specific frustrating event

Exit criteria: There is a problem statement that does not mention any solution or technology.

State RA1: Solution-first thinking

Symptoms: Technology choices before the problem is clear ("need a database", "should use React"); requirements describe implementation rather than needs; requirements cannot be explained without referring to technology.

Key questions：

"What is the need behind this feature?"
"If this technology did not exist, what would you still need?"
"Are you solving your problem or copying someone else's solution?"
"Is this technology necessary (a constraint) or just familiar (a preference)?"

Intervention：

"Delete the solution" exercise: describe the need without any implementation words
Feature extraction: rewrite each requirement as "the system must [verb]..." without technical jargon
Distinguishing constraints from preferences: separate hard constraints from defaults

Exit criteria: each requirement describes the need, not the implementation. Technical references are either removed or explicitly documented as genuine constraints.

State RA2: Vague requirements

Symptoms: unable to describe what "done" looks like; adjective-based requirements ("fast", "simple", "intuitive"); untestable requirements; "users should be able to..." without specifics.

Key questions：

"Can you give a concrete example scenario?"
"Compared with an excellent implementation, what would a disappointing implementation look like?"
"What is the minimum needed to satisfy this requirement?"
"How do you know whether this requirement has been met?"

Intervention：

Acceptance scenario writing: "Given [context], when [action], then [outcome]"
Specificity ladder: who specifically? does what specifically? when specifically?
"Done looks like..." exercise: describe the smallest thing that would satisfy it
Testability check: if you cannot write a test for it, then you do not yet understand it

Exit criteria: every requirement has acceptance criteria. No more adjective-only requirements.

State RA3: Hidden constraints

Symptoms: unexpected dependencies appear late; no clear constraint inventory; assumptions are treated as facts; blockers are discovered during discussion.

Key questions：

"What external dependencies exist?"
"What resources, skills, and time do you actually have?"
"What would kill this project if it turned out to be true?"
"What facts do you believe that you have not yet verified?"

Intervention：

Constraint inventory: list budget, time, skills, dependencies, integration asreal constraints
Assumption mapping: separate verified facts from unverified assumptions
Risk pre-mortem: "6 months from now, this failed. Why?"
Dependency discovery: what must exist before this?

Exit criteria: a constraint inventory exists that clearly distinguishes actual constraints from assumptions.

State RA4: Scope creep

Symptoms: every feature feels equally important; no V1 boundary; "while we're at it..." additions; requirements grow faster than they are satisfied.

Key questions：

"If you could ship only 3 things, what would they be?"
"What can you cut and still solve the core problem?"
"What is the smallest useful version?"
"What would trigger reconsidering a deferred item?"

Intervention：

Cut-first approach: start with everything, add only what is necessary
Strength ranking: strict ordering, no ties
Walking skeleton: identify the thinnest useful version
MoSCoW: Must/Should/Could/Won't
Deferred feature list with explicit triggers for reconsideration

Exit criteria: The V1 boundary is clear. Deferred items are listed with triggers. There is no ambiguity about what is in scope.

Note RA5: Requirements verified

Metrics：

Problem statements exist but have no solution references
Every requirement can be tested through acceptance criteria
Constraints (real and assumed) are listed
Scope is limited by an explicit V1 definition
Requirements can be explained to someone unfamiliar and they can understand them

Next step: Hand off the verified requirements document to "Design Solution".

Phase 2: Validation — Confirm with the user

Present a requirements summary in a structured format(see Output section)
Request explicit approval: "Do these requirements accurately reflect your needs?"
Iterate if needed: If gaps are found, return to the relevant state

Phase 3: Persist — Write the document

Determine the output location：
- Default:docs/requirements-planning/<topic>.md
- Compatibility: Existing projects using docs/需求/<topic>.md may temporarily keep that path
- Ask the user whether a different location is preferred
Write the document according to the output template
Commit to version control
Announce completion and hand off

Input and Output (Input & Output)

Input (Input)

User request: A vague idea, feature request, problem statement, or existing requirements that need validation.
Project context: Existing codebase, documentation, constraints (discovered during exploration).
User responses: Answers to diagnostic questions, evaluation feedback, approval of verified requirements.

Output (Output)

Verified requirements document

# [Topic] Requirements

**Date:** YYYY-MM-DD
**Status:** Validated
**Approved by:** [User name or "User"]

## Problem Statement

[Who has what problem and why it matters. No solution or technology references.]

## Need Hierarchy

### Must Have (V1)

| ID | Need | Acceptance Criteria | Status |
| :--- | :--- | :--- | :--- |
| R-01 | [Testable need] | Given [X], when [Y], then [Z] | Validated |
| R-02 | [Testable need] | [Measurable criterion] | Validated |

### Should Have (V1 if time permits)

| ID | Need | Acceptance Criteria | Status |
| :--- | :--- | :--- | :--- |
| R-03 | [Testable need] | [Criterion] | Validated |

### Could Have (Post-V1)

| ID | Need | Trigger to reconsider | Status |
| :--- | :--- | :--- | :--- |
| R-04 | [Deferred need] | [When to revisit] | Deferred |

## Constraint Inventory

### Real Constraints (Validated)

- [Budget, time, skills, dependencies, integrations]

### Assumptions (Unvalidated)

- [Assumptions that need validation, with plan to validate]

## Scope Definition

- **In scope (V1):** [Explicit list]
- **Out of scope:** [Explicit list]
- **Walking skeleton:** [Thinnest useful version]

## Open Questions

- [Any remaining unknowns with plan to resolve]

Status Lifecycle (Status Lifecycle)

The initial status of each requirements entry generated by this skill should be set to Validated(Verified) or Deferred(Deferred). Downstream execution, planning, or development processes (for example, breakdown-tasks and the execution Agent) are responsible for updating the status of these requirements in the document during implementation (for example, updating to In Progress、Implemented、Dropped , etc.). This skill is not responsible for status updates after that.

Conversation and Files

Go to file	Keep conversation state
Problem statement	Five Whys exploration
Requires a hierarchy with acceptance criteria	Prioritization discussion
Limit inventory	Assumption discovery conversation
Scope definition	Cut/keep negotiation
Validate requirements	Clarifying questions

Limits (Limits)

Hard Boundaries (Hard Boundaries)

No design before validation: Before requirements are validated, do not propose architecture, choose technologies, or create designs.
No skipping states: If the problem is unclear (RA0), do not discuss requirements (RA2) or scope (RA4). Proceed in order.
One question at a time: Do not overwhelm the user with multiple diagnostic questions in one message.
Developer decides: Diagnosis, questioning, and guidance - the developer makes the final decision on priorities and scope.
Do not accept ambiguity: Do not accept adjective-based requirements ("fast", "intuitive"). Push for testable criteria.
No solution language: Requirements must describe the problem and the need, not the implementation. Flag and rewrite solution-disguised requirements.

Skill Boundaries (avoid overlap)

Do not do these (other skills can handle them)：

Design and architecture: Propose solutions, choose technologies, create design documents → use "Design Solution"
Implementation planning: Create task lists, file paths, code structure → use the implementation planning skill
Code writing: Write any implementation code → use the development skill
Code review: Review existing code → usereview-code
Skill refinement: Improve skill documentation → userefine-skill-design

When to stop and hand off：

User says "approved", "looks good", "continue" → requirements verified, hand off to "Design Solution"
User asks "How should we design this?" → hand off to "Design Solution"
User asks "Can you write the code?" → requirements complete, hand off to the development workflow (if skipped, suggest the design step)
User says the requirements are "good enough" → confirm all success criteria are met, then hand off

Self-Check

Core success criteria (all criteria must be met)

Problem is clear: A clear problem statement exists, but with no solution or technical references
Requirements are testable via IDs: Each requirement has acceptance criteria and a unique "R-NN" ID; IDs are sequential, with no gaps or duplicates
Explicit state management: Each requirement entry has an explicit initial state (such as Validated), and the output includes a status column
Listed constraints: Actual constraints separated from assumptions
Scope is bounded: V1 boundaries are clear, with deferred items and triggers recorded
User confirmation: The user explicitly approves the verified requirements
Document retention: The requirements document is written todocs/requirements-planning/<topic>.mdand committed

Process quality check

No skipped states: Diagnostic states proceed in order (no jumping from RA0 to RA4)
One question at a time: The user is not overwhelmed by multiple questions per message
No solution language: Requirements describe the need, not the implementation
Developer decides: Guide and challenge, but the developer makes the final priority and scope calls
Adjectives resolved: No vague adjectives, only requirements remain ("fast", "intuitive", "simple")
Assumption separation: unverified assumptions are marked separately from actual constraints
Reviewed IDs: all requirement IDs follow the "R-NN" format, are unique, and are used for cross-references within the document

Health Check Questions

Before declaring requirements verified, ask yourself:

If the project fails, what is the most likely requirement-related reason?
Are developers building what they need or what they know how to build?
What is explicitly out of scope?
Is the scope achievable under actual constraints?
Which assumptions have not been verified?
Can someone unfamiliar interpret the requirements correctly?

Acceptance Test

Can someone unfamiliar with the project read the requirements document and understand the problem, who has this problem, what "done" looks like, and what is out of scope—without needing to ask clarifying questions?

If no: requirements are incomplete. Return to the earliest unresolved state.

If yes: requirements are verified. Persist and hand off to "Design Solution".

Examples (Example)

Example 1: Greenfield project—"I want to build a static site generator"

User: "I want to build a static site generator."

Agent announces: "Before any design or implementation, I am using the Analyze Requirements skill to verify requirements."

Classification: clarity 30%, specificity 10%, completeness 10%. Start from RA0.

RA0 — Problem Discovery：

Agent: "What specific frustrations with existing static site generators led to this idea?"

User: "I'm tired of the complexity. I just want to write Markdown and get HTML."

Agent: "What do you do today?"

User: "I use Hugo, but I spend more time debugging configuration than writing content."

Captured problem statement: "Solo content creators waste time debugging SSG configuration instead of writing. Need a zero-config path from Markdown to HTML."

RA1 — Solution-First Check：

Agent: "You mentioned Hugo—is there anything specific about Hugo you need to keep? Or is "Markdown → HTML" the core requirement regardless of what tool is used?"

User: "Just Markdown to HTML. I don't care how."

Exit RA1: need confirmed without technical lock-in.

RA2 — Specificity：

Agent: "What would the simplest useful version of 'done' look like?"

User: "I point it at a folder of .md files, and I get a folder of .html files with basic styling."

Agent: "How do you know the output is correct?"

User: "Every .md file produces an .html file. Links between pages work. It looks readable on mobile."

Captured acceptance criteria：

R-01: every.mdfile → one.htmlfile (1:1 mapping)
R-02: internal links resolve correctly
R-03: output is readable on mobile (viewport meta, readable font size)

RA3 — Constraints：

Agent: "What time and skills do you have to do this?"

User: "Evenings and weekends, about 10 hours a week. I know JavaScript well."

Constraint inventory: Time: 10 hours/week; Skills: JavaScript proficiency; Dependencies: undetermined.

RA4 — Scope：

Agent: "If you could only ship 3 features, what would they be?"

User: "Markdown to HTML, basic CSS, and a dev server with live reload."

Scope definition：

V1 must: Markdown→HTML, default CSS, dev server
Deferred: themes, plugins, custom templates (trigger: 2 weeks after V1 is available)
Walking skeleton: a CLI that converts one .md file to .html CLI

RA5 — Validated: The agent provides a summary, and the user says "looks good." The document is written to "docs/requirements-planning/static-site-generator.md".

Example 2: Edge case — solution disguised as a requirement

User: "I need a React app with a PostgreSQL database, a GraphQL API, and Redis caching."

Agent announces: "Before any design or implementation, I am using the requirements-analysis skill to validate the requirements."

Classification: Clarity 60% (clear technology), specificity 20% (no stated problem), completeness 15%. Start from RA0.

RA0 — Problem discovery：

Agent: "These are all technology choices. What problem are you trying to solve? Who has the problem?"

User: "Oh... I need to track inventory for my small business. I currently use a spreadsheet and keep losing data."

Problem statement: "Small business owners lose inventory data due to spreadsheet limitations. Reliable inventory tracking is needed."

RA1 — Solution-first cleanup：

Agent: "Let's rewrite the requirements without technology. 'React, PostgreSQL, GraphQL, Redis' are all solutions. What requirements do they represent?"

Rewritten:

React app → "needs a user interface accessible from multiple devices"
PostgreSQL → "data must persist and not be lost after the server restarts"
GraphQL API → "needs flexible querying of inventory (by name, category, location)"
Redis cache → "frequently accessed data should load quickly"

Agent: "Can 'load quickly' be tested? How fast is acceptable?"

User: "The inventory list page in less than 2 seconds."

Exit RA1: Rewrite requirements as needed. Technology choices are deferred to the design phase.

RA2–RA5: Continue through the states. The final document captures requirements without technology assumptions, allowing "design solution" to explore the right solution (which may be a simple spreadsheet replacement rather than a full-stack app).

Example 3: Edge case — mid-project scope creep

User: "We started building a to-do app, but now it needs calendar integration, team collaboration, file attachments, and AI-driven task suggestions. We're 3 weeks behind."

Agent announces: "Before expanding scope, I'm using the requirements analysis skill to validate the requirements."

Classification: Clarity 50%, specificity 40%, completeness 30%. Scope creep symptoms — start from RA4 (the earlier state may be resolved after 3 weeks, but needs verification).

Quick RA0 check: "What was the original problem this to-do app solved?"

User: "I need to stop forgetting my freelance project tasks and deadlines."

Problem confirmed — proceed with RA4.

RA4 — Scope creep intervention：

Agent: "If you could only deliver 3 features from the full list, which 3 would solve the core problem of not forgetting tasks?"

User: "Basic task list, deadlines with reminders, and... that's it for now."

Agent: "So calendar integration, team collaboration, file attachments, and AI suggestions are all extras beyond the core problem. Should we defer them?"

Scope redefinition：

V1 Must: task CRUD, deadlines, reminders
Deferred: calendar integration (trigger: 1 month after using reminders), collaboration (trigger: when a freelancer becomes a team), attachments (trigger: user request), AI suggestions (trigger: 100+ tasks)
Walking skeleton: CLI or simple UI that can create tasks with deadlines and send reminder notifications

RA5 — Verified: Requirements refocused. The 3-week delay becomes manageable. Documentation updated.

Anti-patterns

Solution specification

Problem: The requirements describe an implementation, not a requirement. "The system should use PostgreSQL" is not required; "data must persist after a server restart" is.

Fix: For each requirement, ask "could this be satisfied in a different way?" If yes, you captured an implementation, not a requirement.

Stakeholder fiction

Problem: Developers imagine requirements instead of discovering them. "Users will want..." with no evidence.

Fix: If you are the user, state your needs honestly. If building for others, talk to them or cite similar evidence. Don't invent users.

Infinite backlog

Problem: Requirements keep growing without prioritization. Everything is equally important.

Fix: Force a ranking. If you could only ship one thing, what would it be? Then two? This reveals the actual priorities.

Premature precision

Problem: Specifying details that aren't important yet. Designing notification preferences before validating that anyone wants notifications.

Fix: Stub uncertain areas with "[X] pending validation". Focus precision on V1 Must items.

Constraint blindness

Problem: Didn't take stock of the real constraints, then address them during the build.

Fix: Explicitly bound the inventory before finalizing requirements.

Appendix: Integration Map

Upstream (feeds into this skill)

Source	When	What it provides
User request	New project or feature idea	Raw intent analysis
Existing documentation	Mid-project validation	Partial requirements diagnosis

Downstream (this skill feeds into)

Target skill	When	What it receives
`设计解决方案`	Requirements verified	Verified requirements document as design input
Implementation planning	Design is trivial	Verified requirements scope and constraints

Handoff contract

This skill outputs	Target skill expects
Problem statement	Design context
Hierarchy with acceptance criteria is needed	Functional requirements
Bound the inventory	Architectural constraints
Scope definition (V1 boundary)	Design scope

About this skill

Purpose

Core Objective

Scope Boundaries

Use Cases

Behavior (Behavior)

Interaction (Interaction) Policy

Hard gate: no design before verification

Phase 0: Triage

Phase 1: Diagnosis — Determine the current state

State RA0: No problem statement

State RA1: Solution-first thinking

State RA2: Vague requirements

State RA3: Hidden constraints

State RA4: Scope creep

Note RA5: Requirements verified

Phase 2: Validation — Confirm with the user

Phase 3: Persist — Write the document

Input and Output (Input & Output)

Input (Input)

Output (Output)

Verified requirements document

Status Lifecycle (Status Lifecycle)

Conversation and Files

Limits (Limits)

Hard Boundaries (Hard Boundaries)

Skill Boundaries (avoid overlap)

Self-Check

Core success criteria (all criteria must be met)

Process quality check

Health Check Questions

Acceptance Test

Examples (Example)

Example 1: Greenfield project—"I want to build a static site generator"

Example 2: Edge case — solution disguised as a requirement

Example 3: Edge case — mid-project scope creep

Anti-patterns

Solution specification

Stakeholder fiction

Infinite backlog

Premature precision

Constraint blindness

Appendix: Integration Map

Upstream (feeds into this skill)

Downstream (this skill feeds into)

Handoff contract