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.

Step 5: Transition

Tell the user: "Problem defined. Run /spec to turn this into a buildable specification."

If the user wants to explore further (e.g., they realize there are actually 3 problems), loop back to Step 2 with the new angle.

Why: The transition from problem to spec is natural but explicit. The user owns the decision to move forward.

When to Trigger

Auto-trigger (no command needed):

• User's request lacks a clear problem or goal
• User names a technology/solution without explaining why
• User describes symptoms without identifying the underlying issue
• User says "I don't know where to start" or equivalent
• Request is so broad it could mean 3+ different things

Explicit invocation (/discover):

• User wants to formally start the discover phase for a new project or feature
• User wants to re-explore a problem before re-specifying
• Continuation from a previous discovery session

Anti-Rationalization

Evidence Required

Before claiming the problem is defined, show ALL of these:

• Problem statement written in the structured format (Who / Problem / When / Impact / Desired state)
• Root cause or job story identified
• At least one measurable/observable criterion for success
• User confirmed the frame is accurate
• Scope boundaries stated (what's in and out)

"I think I understand" without a written problem statement = guessing.

Red Flags

• Jumping to solutions or code during the discovery conversation
• Asking more than 3 questions per round (overwhelming the user)
• Running more than 3 rounds without attempting a frame (analysis paralysis)
• Ignoring when the user says "I'm not sure" — that IS information
• Producing a problem statement the user didn't confirm
• Confusing symptoms with root causes
• Framing the problem so broadly it could mean anything ("improve the system")
• Skipping discovery for non-trivial, ambiguous work

Output Format

Save to $HARNESS_DIR/specs/PROBLEM-{timestamp}.md:

---
status: framed
created: {ISO-8601 timestamp}
context: {one-line summary}
---

# Problem: {title}

## Problem Statement
{Who} experiences {observable problem} when {trigger condition}, resulting in {quantified impact}. The desired state is {measurable outcome}.

## Root Cause / Job Story
{5 Whys chain or JTBD job story}

## Constraints
- Timeline: {when is this needed}
- Technology: {stack constraints}
- Scale: {expected load/users}
- Compatibility: {backward-compat requirements}

## Assumptions
- {assumption} — {certain / uncertain}
- {assumption} — {certain / uncertain}

## Out of Scope
- {what this problem explicitly does NOT cover}