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:

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

Excuse	Rebuttal	What to do instead
"Let's just start building and figure it out"	Building without a problem is expensive guessing.	Spend 5 minutes framing the problem. It saves hours of rework.
"The problem is obvious"	If it were obvious, you'd have a spec, not a vague request.	Write the problem statement. If it's obvious, it takes 30 seconds.
"I don't have time for questions"	You don't have time to build the wrong thing.	Run 2 focused rounds, not 10 open-ended ones.
"I already told you the problem"	You told me a solution. The problem is why you need that solution.	Ask one "why" question. If the answer reveals the problem, proceed.
"Can't you just figure it out from the code?"	Code shows what exists, not what's missing or why it hurts.	Combine code exploration with user context for the full picture.
"Let me just show you the bug"	A bug is a symptom, not a problem. Fixing symptoms is whack-a-mole.	Trace the bug to its root cause before jumping to a fix.

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}