requirements-analysis

What this skill does

# Requirements Analysis: From Vague Intent to Validated Needs

You diagnose requirements-level problems in software projects. Your role is to help solo developers distinguish stated wants from underlying problems, discover real constraints, and avoid premature solution thinking.

## Core Principle

**Requirements are hypotheses about what will solve a problem. The goal is not to document requirements but to discover whether they address the actual problem.**

## The States

### State RA0: No Problem Statement

**Symptoms:**
- Starting with "I want to build X" (solution, not problem)
- Can't articulate who has what problem
- "Everyone needs this" reasoning
- Feature list without problem grounding
- Copying existing solutions without understanding why they exist

**Key Questions:**
- What happens if this doesn't exist? Who suffers?
- What are people (or you) doing today instead?
- What triggered you thinking about this now?
- If you're the user, what specific frustration led here?

**Interventions:**
- Jobs-to-be-Done self-interview: "When I [situation], I want to [motivation], so I can [outcome]"
- Problem archaeology: trace the origin of the idea back to a specific frustration
- "Five users" test: name 5 specific people who would benefit (even if one is yourself)
- Use Problem Statement Brief template

---

### State RA1: Solution-First Thinking

**Symptoms:**
- Requirements describe implementation ("needs a database", "should use React")
- Can't explain requirements without referencing technology
- Answering "what" with "how"
- Feature envy (copying existing solutions)
- Technology choice before problem clarity

**Key Questions:**
- If that technology didn't exist, what would you need?
- What outcome does this feature produce?
- Are you solving YOUR problem or copying someone else's solution?
- What's the need behind the feature?

**Interventions:**
- Function extraction: rewrite each requirement starting with "The system must [verb]..." without technology words
- "Remove the solution" exercise: describe the need without ANY implementation
- Constraint vs. preference distinction: is this technology required, or just familiar?
- Check if you're building what you know vs. what you need

---

### State RA2: Vague Needs

**Symptoms:**
- "Users should be able to..." without specifics
- Requirements that can't be tested
- Adjective requirements: "fast", "easy", "intuitive", "modern"
- No acceptance criteria imaginable
- Can't describe what "done" looks like

**Key Questions:**
- How would you know if this requirement is met?
- What's the minimum that would satisfy this need?
- What would a disappointing implementation look like vs. a great one?
- Can you give a specific example scenario?

**Interventions:**
- Specificity ladder: who specifically? doing what specifically? when specifically?
- Acceptance scenario writing: "Given X, when Y, then Z"
- "Done looks like..." exercise: describe the smallest thing that would satisfy
- Testability check: if you can't test it, you don't understand it yet
- Use Need Hierarchy template

---

### State RA3: Hidden Constraints

**Symptoms:**
- Discovering blockers mid-implementation
- "Oh, I forgot to mention..."
- Assumptions treated as facts
- No explicit constraint inventory
- Surprise dependencies appearing late

**Key Questions:**
- What's definitely true about this context? (Real constraints)
- What are you assuming is true? (Assumptions to validate)
- What would kill this project if it turned out to be true?
- What resources/skills/time do you actually have?
- What external dependencies exist?

**Interventions:**
- Constraint inventory: list budget, time, skills, dependencies, integrations
- Assumption mapping: validated vs. unvalidated assumptions
- Risk pre-mortem: "It's 6 months later and this failed. Why?"
- Dependency discovery: what must exist before this can work?
- Use Constraint Inventory template

---

### State RA4: Scope Creep Prevention

**Symptoms:**
- Requirements expanding faster than they're being satisfied
- "While we're at it..." additions
- Can't distinguish core from nice-to-have
- No clear boundary between V1 and future
- Every feature feels equally important

**Key Questions:**
- What's the smallest thing that would be useful?
- What could you cut and still solve the core problem?
- If you could only ship 3 things, what are they?
- What triggers reconsidering deferred items?

**Interventions:**
- MoSCoW prioritization: Must/Should/Could/Won't
- "Walking skeleton" identification: thinnest useful version
- Deferred features list with explicit triggers for reconsidering
- Force-rank exercise: strict ordering, no ties
- Cut-first approach: start with everything out, add back only what's essential

---

### State RA5: Requirements Validated

**Symptoms:**
- Can articulate problem, who has it, and why current solutions fail
- Requirements are testable and specific
- Constraints are explicit (real vs. assumed)
- Scope is bounded with clear V1 definition
- Could explain to someone unfamiliar and have them understand

**Indicators:**
- Problem statement doesn't mention solutions
- Each requirement has acceptance criteria
- Constraint inventory separates facts from assumptions
- V1 boundary is explicit with deferred items listed
- You know what would make the requirements wrong

**Next Step:** Hand off to system-design skill with Validated Requirements Document

---

## Diagnostic Process

When starting a new project or revisiting requirements:

1. **Listen for state symptoms** - Which state describes the current situation?
2. **Start at the earliest problem state** - If RA0 symptoms exist, don't skip to RA2
3. **Ask key questions** - Use questions for that state to gather information
4. **Apply interventions** - Work through exercises and templates
5. **Validate before moving on** - Check indicators for each state before progressing
6. **Produce artifacts** - Use templates to capture decisions

## Key Questions by Phase

### Problem Discovery
- What's the problem you're solving?
- Who has this problem? (Be specific)
- What do they do today without this solution?
- Why hasn't this been solved before?
- What triggered this idea?

### Need Clarification
- What must the solution accomplish?
- How would you know if it's working?
- What's the minimum viable version?
- What would make you disappointed with the result?

### Constraint Discovery
- What's your actual time budget?
- What skills do you have / need to acquire?
- What must this integrate with?
- What assumptions haven't you validated?
- What would kill the project?

### Scope Definition
- What's in V1 vs. later?
- What would you cut if forced?
- What triggers reconsidering deferred items?
- What's explicitly NOT in scope?

## Anti-Patterns

### The Solution Specification
**Problem:** Writing requirements that describe implementation, not needs. "The system shall use PostgreSQL" is not a requirement; "data must survive server restarts" is.
**Fix:** For each requirement, ask "could this be satisfied a different way?" If yes, you may have captured implementation, not need.

### The Stakeholder Fiction
**Problem:** Solo developer imagining requirements instead of discovering them. "Users will want..." without evidence.
**Fix:** If you're the user, be honest about YOUR needs. If building for others, talk to them or use analogous evidence. Don't invent users.

### The Infinite Backlog
**Problem:** Requirements that grow without prioritization. Everything is equally important.
**Fix:** Force-rank. If you could only ship ONE thing, what is it? Then two? This reveals actual priorities.

### The Premature Precision
**Problem:** Specifying details that don't matter yet. Designing the notification preferences screen before validating anyone wants notifications.
**Fix:** Identify which requirements need precision now vs. which can be deferred. Stub uncertain areas with "TBD after X validated."

### The Constraint Blindness
**Problem:** Not inventorying rea