Discover

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:

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

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:

• Root cause (from 5 Whys) or Job story (from JTBD)
• Constraints: timeline, technology, scale, compatibility
• Assumptions: what must be true, which are uncertain
• Out of scope: what this problem explicitly does NOT cover

Show the frame to the user and ask: "Does this capture the problem accurately?"

Why: A written problem statement is testable. If you can't write one, you haven't discovered the problem yet.

Step 4: Save

Once confirmed, save the problem statement:

mkdir -p "$HARNESS_DIR/specs"

Write to $HARNESS_DIR/specs/PROBLEM-{timestamp}.md (see Output Format below).

If the user realizes there are multiple problems during probing, address them one at a time. Each problem gets its own file.