skills/problem-analysis/SKILL.md

name, description

name	description
problem-analysis	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:

# 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