---
name: problem-analysis
description: Deeply understand a problem before coding begins. Identify the real problem, stakeholders, constraints, and success criteria. Use before starting any non-trivial feature.
---

# Problem Analysis

## Core Principle

**Understand WHAT needs to be solved and WHY — before considering HOW.**

Premature solution thinking is one of the most expensive mistakes in software. A feature built on a misunderstood problem is waste, no matter how well it's coded.

> "A problem well-stated is a problem half-solved." — Charles Kettering

## When to Use

**Always use before:**
- Starting any non-trivial feature (more than a day's work)
- Tackling a vague or ambiguous requirement
- Making an architectural decision
- Starting a new project or significant component

**When NOT to use:** Bug fixes with clear reproduction steps, one-line changes, configuration updates.

## The Analysis Process

### Step 1: Understand the Real Problem

Don't accept the first statement of a problem at face value. Dig to the real underlying issue.

**Questions to ask:**
- What is the user actually trying to accomplish?
- What pain or friction does this create today?
- Why is this a problem now? What changed?
- What happens if we don't solve it?
- Who else is affected?

**The 5 Whys technique:** Ask "why" five times to reach the root cause.

```
Problem: "The invoice export is too slow"
Why? → "Users have to wait 30 seconds"
Why? → "We're generating all 5000 invoices in a single query"
Why? → "The feature was built for 50 invoices, now there are 5000"
Why? → "We didn't anticipate growth"
Root: "Batch processing architecture needed, not performance tuning"
```

The solution to "export is slow" might be pagination, async export, or caching — not just query optimization.

### Step 2: Identify Stakeholders and Their Perspectives

Every stakeholder has a different view of the problem.

| Stakeholder | Typical concern |
|-------------|----------------|
| End user | "I need to accomplish X in Y time" |
| Business | "This costs us money / blocks revenue" |
| Ops/DevOps | "This creates operational burden" |
| Compliance | "This creates regulatory risk" |
| Developer | "This is hard to maintain or extend" |

**Map the stakeholders:** Who is directly affected? Who is indirectly affected? Who has authority over the solution?

### Step 3: Define User Needs and Pain Points

Move from "what users say they want" to "what users actually need."

```
User says: "I need a report with 20 columns"
User needs: "I need to identify which customers are at risk of churning"

These may have completely different solutions.
```

**Techniques:**
- User journey mapping: walk through the current process step by step
- Pain point identification: where is friction, delay, error, confusion?
- Job-to-be-done framing: "When [situation], I want to [motivation], so I can [outcome]"

### Step 4: Clarify Requirements and Constraints

**Functional requirements:** What must the system do? (In user terms, not technical terms)
- "Users can export invoices as PDF"
- "The system sends a confirmation email within 5 minutes"

**Non-functional requirements:** How must the system behave?
- Performance: "Export completes in under 5 seconds for 90% of users"
- Security: "Only authenticated users can view their own invoices"
- Availability: "Export feature available 99.9% of the time"

**Constraints:** What is fixed and non-negotiable?
- Budget/time
- Existing systems that must be integrated
- Regulatory requirements
- Technology choices already made

### Step 5: Clarify Scope

Explicitly define what is **in scope** and what is **out of scope**. Out-of-scope items are often as important as in-scope items for preventing scope creep.

**Template:**
```
In scope:
- [Feature A]
- [Feature B]

Out of scope (for this version):
- [Feature C] — will be addressed in v2
- [Feature D] — not part of this problem

Assumptions requiring validation:
- [Assumption 1]
- [Assumption 2]
```

### Step 6: Define Success Criteria

Success criteria must be specific and testable. Vague criteria are not criteria.

```
Vague: "Make the dashboard faster"

Specific and testable:
- Dashboard LCP < 2.5s on a 4G connection (measured with Lighthouse)
- Initial data load completes in < 500ms (measured from API call to render)
- Page is usable within 3s even if non-critical data hasn't loaded
```

**Success criteria format:** `[Metric] [comparison] [threshold] [measurement method]`

### Step 7: Identify Risks and Unknowns

| Category | Questions to ask |
|----------|-----------------|
| Technical | Do we know how to build this? What might surprise us? |
| Business | Does the market actually want this? Is the problem real? |
| Regulatory | Are there compliance implications? |
| Operational | Will this create new operational burden? |
| Integration | What external systems does this depend on? |

## Output: Problem Analysis Document

The analysis should produce a `problem-analysis.md` document covering:

```markdown
# Problem Analysis: [Feature/System Name]

## Problem Statement
[One paragraph: what problem exists, for whom, and why it matters]

## Context
[How this problem arose, what triggered the need to solve it now]

## Stakeholders
| Stakeholder | Role | Primary concern |
|------------|------|----------------|
| [Name/role] | [Decision maker/user/affected] | [Their core need] |

## User Needs and Pain Points
- [Pain point 1]: [Specific friction or failure today]
- [Pain point 2]: ...

## Functional Requirements
(In user terms, not technical terms)
- [ ] [Requirement 1]
- [ ] [Requirement 2]

## Non-Functional Requirements
- Performance: [specific, measurable]
- Security: [specific]
- Availability: [specific]

## Scope
**In scope:** [list]
**Out of scope:** [list]

## Assumptions Requiring Validation
- [Assumption 1]: [How to validate]
- [Assumption 2]: ...

## Risks and Unknowns
| Risk | Impact | Likelihood | Mitigation |
|------|--------|-----------|-----------|
| [Risk 1] | High/Med/Low | High/Med/Low | [Strategy] |

## Success Criteria
- [Metric]: [threshold] ([measurement method])
- [Metric]: [threshold] ([measurement method])

## Open Questions
- [Question requiring answer before implementation begins]
```

## Mathias Context

As a digital PM building production software:

- **Capture the why:** The problem document should capture business context, not just technical requirements. Agents reading it should understand why this matters.
- **Think about the user journey:** Walk through the entire experience, not just the feature in isolation.
- **Challenge the requirement:** Is this the right problem to solve? Is there a simpler solution?
- **Estimate impact:** How many users are affected? How often? What's the cost of not solving it?

## Transition to Next Steps

After the problem is understood:

1. Load `user-stories` skill to decompose into implementable stories
2. Load `spec-driven-dev` skill to write a technical specification
3. Load `planning` skill to break into tasks

**Do NOT jump to implementation.** A complete problem analysis prevents the most expensive mistakes.

## Red Flags — When Analysis Is Incomplete

- Requirements stated in technical terms ("add an index") instead of user terms ("make search faster")
- No clear success criteria ("it should be better")
- No stakeholders identified
- Assumptions not written down
- Scope not defined
- "We know what we need to build" — this is usually premature