Problem Framing

Transform a raw project idea into a structured PROBLEM_BRIEF.md artifact. This is the first step in the greenfield specification pipeline — it takes unstructured input and produces a well-defined problem statement that feeds into requirements decomposition.

When to Use This Skill

• A user has a new project idea (even vague or incomplete)
• You need to establish the scope boundaries before requirements analysis
• The problem space needs clarification before technical work begins

Pipeline Position

[Raw Idea] → **PROBLEM FRAMING** → [PROBLEM_BRIEF.md] → Requirements Decomposition → ...

Input: Raw idea text (from user prompt or --idea flag) Output: PROBLEM_BRIEF.md written to the project's artifacts directory

Process

Step 1: Extract Core Problem

Read the raw idea and identify:

• What problem does this solve?
• Who has this problem?
• Why does it matter?

If the idea is too vague, identify what's missing and document in Open Questions.

Step 2: Identify Target Users

Create a user type table with at least 2 user types:

• Primary users (direct beneficiaries)
• Secondary users (administrators, operators, stakeholders)
• Edge users (occasional or power users)

Step 3: Define Success Metrics

Create measurable success metrics with IDs (SM-0001, SM-0002, ...):

• Each metric must have a target value
• Each metric must have a measurement method
• Metrics should cover: adoption, engagement, performance, business value

Step 4: Document Constraints

Identify technical, business, regulatory, and resource constraints:

• Use IDs: CON-0001, CON-0002, ...
• Categorize: Technical, Business, Regulatory, Resource, Timeline

Step 5: Define Non-Goals

Explicitly state what is OUT of scope:

• Use IDs: NG-0001, NG-0002, ...
• Non-goals prevent scope creep and set expectations

Step 6: Write Problem Statement

Synthesize all above into a clear, falsifiable problem statement:

• 2-4 sentences
• States the problem, who it affects, and the desired outcome
• Does NOT prescribe a solution

Output Format

Write the artifact following the template at ${CLAUDE_PLUGIN_ROOT}/reference/templates/PROBLEM_BRIEF.template.md.

The artifact must follow the standard artifact template structure:

# PROBLEM_BRIEF: [Project Name]

## Summary
[2-3 sentence summary of the problem being solved and why it matters]

## Inputs
- **Raw Idea**: [The original idea text provided by the user]
- **Additional Context**: [Any supplementary information provided]

## Outputs
- This document (PROBLEM_BRIEF.md)
- Feeds into: REQUIREMENTS.md (via requirements-decomposition skill)

## Assumptions
- [ASM-0001]: [Assumption text — sorted alphabetically, sequential IDs]
- [ASM-0002]: [Assumption text]
- ...

## Open Questions
- [OQ-0001]: [Question text — things that need clarification before proceeding]
- [OQ-0002]: [Question text]
- ...

## Main Content

### Problem Statement
[2-4 sentences. States the problem, who it affects, and the desired outcome.
Must be falsifiable. Must NOT prescribe a solution.]

### Target Users

| User Type | Description | Primary Need | Frequency of Use |
|-----------|-------------|--------------|------------------|
| [Type 1]  | [Who they are] | [What they need] | [How often] |
| [Type 2]  | [Who they are] | [What they need] | [How often] |
| [Type 3]  | [Who they are] | [What they need] | [How often] |

### Success Metrics

| ID | Metric Name | Target Value | Measurement Method | Category |
|----|-------------|--------------|-------------------|----------|
| SM-0001 | [Name] | [Measurable target] | [How to measure] | [adoption/engagement/performance/business] |
| SM-0002 | [Name] | [Measurable target] | [How to measure] | [Category] |
| SM-0003 | [Name] | [Measurable target] | [How to measure] | [Category] |

### Constraints

| ID | Constraint | Category | Impact |
|----|-----------|----------|--------|
| CON-0001 | [Constraint text] | [Technical/Business/Regulatory/Resource/Timeline] | [How it affects the project] |
| CON-0002 | [Constraint text] | [Category] | [Impact] |

### Non-Goals

| ID | Non-Goal | Rationale |
|----|----------|-----------|
| NG-0001 | [What is explicitly out of scope] | [Why it is excluded] |
| NG-0002 | [Out of scope item] | [Rationale] |

## Acceptance Criteria
- [ ] Problem statement is clear, falsifiable, and does not prescribe a solution
- [ ] At least 2 target user types identified with descriptions
- [ ] At least 3 success metrics with measurable targets and measurement methods
- [ ] Constraints documented with categories and impact assessment
- [ ] Non-goals explicitly stated with rationale
- [ ] All IDs are sequential and items are sorted alphabetically by title/text
- [ ] Assumptions documented for any gaps in information
- [ ] Open questions listed for items requiring clarification

Output path: artifacts/greenfield/<project_name>/PROBLEM_BRIEF.md

Determinism Rules

1. Assumption IDs (ASM-NNNN): Sort alphabetically by assumption text, assign sequential numbers starting from 0001
2. Constraint IDs (CON-NNNN): Sort alphabetically by constraint text, assign sequential numbers starting from 0001
3. Non-Goal IDs (NG-NNNN): Sort alphabetically by non-goal text, assign sequential numbers starting from 0001
4. Open Question IDs (OQ-NNNN): Sort alphabetically by question text, assign sequential numbers starting from 0001
5. Success Metric IDs (SM-NNNN): Sort alphabetically by metric name, assign sequential numbers starting from 0001
6. No timestamps in artifact body
7. Sections must appear in template order
8. User types listed in order: Primary, Secondary, Edge
9. Success metric categories ordered: adoption, engagement, performance, business

Handling Incomplete Input

When the raw idea is vague or incomplete:

1. Extract what you can: Even a one-sentence idea has implicit users and problems
2. State assumptions explicitly: Use ASM-NNNN IDs for every inference you make
3. Flag open questions: Use OQ-NNNN IDs for everything that needs user clarification
4. Do NOT invent requirements: Keep the problem brief grounded in what was stated
5. Do NOT hallucinate metrics: If you cannot derive a meaningful metric, document it as an open question

Vagueness Escalation

Input Quality	Action
Clear and detailed	Proceed normally, minimal assumptions
Moderate detail	Proceed with documented assumptions, 2-3 open questions
Vague (1-2 sentences)	Proceed with heavy assumptions, 5+ open questions, flag for review
Extremely vague	Generate minimal brief, list all gaps as open questions, recommend user interview

Cross-Referencing

The PROBLEM_BRIEF.md is referenced by downstream artifacts:

• REQUIREMENTS.md: Maps requirements back to problem statement and success metrics
• FUNCTIONAL_SPEC.md: References constraints when defining feature boundaries
• VIABILITY.md: Uses success metrics for business case analysis
• ARCHITECTURE.md: References technical constraints for design decisions

Ensure all IDs are stable — once assigned, they should not change across regenerations unless the underlying content changes.

Quality Checklist

Before completing, verify:

• Problem statement is clear and falsifiable
• Problem statement does NOT prescribe a solution
• At least 2 target user types identified
• At least 3 success metrics with measurable targets
• Each success metric has a measurement method
• Constraints are documented with categories
• Non-goals are explicitly stated with rationale
• All IDs are sequential and sorted alphabetically
• Assumptions are documented for any inferences made
• Open questions capture all ambiguities
• Artifact follows the standard template structure
• All sections appear in the correct order
• No solution language appears in the problem statement

Common Pitfalls

1. Solution masquerading as problem: "We need a mobile app" is a solution. "Users cannot access their data on the go" is a problem.
2. Unmeasurable success metrics: "Users like it" is not measurable. "User satisfaction score > 4.0/5.0 via monthly NPS survey" is measurable.
3. Missing non-goals: Without explicit non-goals, scope creep is inevitable. Every project should have at least 2 non-goals.
4. Overly broad problem statement: "Improve healthcare" is too broad. "Reduce appointment no-show rates for small clinics with < 5 providers" is appropriately scoped.
5. Confusing constraints with requirements: A constraint limits what you can do. A requirement defines what you must do. "Must use PostgreSQL" is a constraint. "Must store patient records" is a requirement.
6. Skipping edge users: Edge users often reveal important boundary conditions that primary user analysis misses.

Examples

Example: Good Problem Statement

"Small-to-medium real estate agencies (5-20 agents) lose an average of 3-5 hours per agent per week on manual lead qualification, resulting in delayed follow-ups and an estimated 15-20% loss in potential conversions. There is no standardized process for scoring and routing incoming leads across the team."

Example: Bad Problem Statement

"We need an AI-powered CRM with automatic lead scoring, email integration, and a mobile app for real estate agents." (This prescribes a solution, not a problem.)