discover

Files (1)

• SKILL.md

SKILL.md (first lines)

# Discover — Problem Discovery

You are starting the **Discover** phase. Your job is to help the user articulate what problem they are actually trying to solve, before jumping to solutions or specs.

**CRITICAL**: Run `HARNESS_DIR=$(epic-harness path)` first. NEVER use `.harness/` in the project directory.

## Iron Law

NO SPEC WITHOUT A PROBLEM STATEMENT. Building the wrong thing well is worse than building the right thing poorly.

## Process

### Step 0: Prerequisites

- Resolve harness directory: `HARNESS_DIR=$(epic-harness path)`
- Read any existing context (CLAUDE.md, README, codebase structure)
- Check for existing problem statements in `$HARNESS_DIR/specs/PROBLEM-*.md`
- Call `mem_recall` with a hint describing the current topic area
- Check for past `decision` or `pattern` nodes related to this domain
- If prior problem exploration exists, reference it: "We discussed something similar before..."
- If existing PROBLEM files are found, review them — the user may be continuing prior work

**Why**: Past context prevents re-exploring ground already covered. The knowledge graph connects today's vague request to yesterday's decisions.

### Step 1: Listen

Read the user's request carefully. Repeat it back in your own words and ask:
- "Is that the core of it, or is there more?"

Categorize the request:

| Category | Signal | Example |
|----------|--------|---------|
| Solution without problem | User names a technology or approach | "Add Redis caching" |
| Feature without context | User describes output, not why | "Build a dashboard" |
| Systemic complaint | Broad negative without specifics | "Everything is slow" |
| Vague ambition | Goal with no boundaries | "Make it better" |
| Clear problem | Observable gap stated | "Login fails for 5% of users" |

**Why**: Categorization determines the probing technique. Misreading the category leads to wrong questions.

### Step 2: Probe

Select the technique based on the category identified in Step 1. Ask **max 3 questions per round**, run **max 3 rounds**. If the user can't answer or says "I'm not sure", proceed to Frame with what you have.

#### Technique Selection

| User signal | Technique | Core question |
|---|---|---|
| Names a solution ("Add Redis") | **5 Whys** | "What's happening that makes you need this?" → repeat |
| Describes a feature without why | **JTBD** | "What situation makes you need this? What would 'done' look like?" |
| "Everything is broken" | **Fishbone** | "Which area: People / Process / Technology / Data / Environment?" |
| Vague or contradictory | **Socratic** | "What specifically do you mean by 'X'?" |
| Has a vision but no path | **Done looks like** | "When this works perfectly, what do you see?" |
| Uncertain assumptions | **Assumption map** | "What must be true for this to work?" |

#### Detailed Technique Reference

**5 Whys** — when the user presents a solution without a problem:
```
User: "Add Redis caching to the API."
→ "What's happening that makes you want caching?"
→ "Why is that slow?"
→ "Why does that query take long?"
```
Stop when you reach an actionable root cause. Max 5 levels.

**JTBD (Jobs To Be Done)** — when the user describes a feature without context:
```
User: "Build a dashboard."
→ "What situation makes you need this?"
→ "What would you do with the information right now?"
→ "What would have to be true for you to say 'this solved it'?"
```
Extract job stories: "When [situation], I want [motivation], so I can [outcome]."

**Fishbone** — when the user has a systemic complaint:
```
User: "Everything is broken."
→ Walk through categories: People, Process, Technology, Data, Environment
→ "Which of these areas is the biggest contributor?"
→ "Is this on all branches or specific ones?"
```
Map causes across categories, then narrow to the top 1-2.

**Socratic Questioning** — when the request is vague or contradictory:
```
User: "Make it more secure." / "I want it to be faster."
→ Clarification: "What specifically do you mean by 'secure' / 'fast'?"
→ Probing assumptions: "What makes you believe this is the issue?"
→ Implications: "If we change X, what happens to Y?"
→ Alternatives: "What other approaches did you consider?"
```

**"What Does Done Look Like?"** — when the user has a vision but no path:
```
→ "When this is shipped and working perfectly, what specifically do you see?"
→ "What would I click, what output would appear, what would the logs show?"
```
Work backwards from the concrete end state.

**Assumption Mapping** — when the request depends on uncertain premises:
```
→ "Let me check what we're assuming must be true for this to work."
→ List 4-5 assumptions, ask which are uncertain.
```
Shaky assumptions become prerequisites.

Each round should narrow the space. If after 2 rounds you have enough to frame, don't force a third.

**Why**: The right technique extracts the real problem in 2-3 rounds instead of 10 random questions. Technique mismatch wastes rounds and frustrates the user.

### Step 3: Frame

Synthesize everything into a structured problem statement:

> **[Who]** experiences **[observable problem]** when **[trigger condition]**, resulting in **[quantified impact]**. The desired state is **[measurable outcome]**.

Capture supporting context:

From epicsagas/epic-harness, Apache-2.0.

More from epicsagas/epic-harness