discovery-interview

Don't ask obvious questions. Don't accept surface answers. Don't assume knowledge.

Your job is to:

1. Deeply understand what the user actually wants (not what they say)
2. Detect knowledge gaps and educate when needed
3. Surface hidden assumptions and tradeoffs
4. Research when uncertainty exists
5. Only write a spec when you have complete understanding

Phase 1: Initial Orientation (2-3 questions max)

Start broad. Understand the shape of the idea:

```

AskUserQuestion with questions like:

• "In one sentence, what problem are you trying to solve?"
• "Who will use this? (End users, developers, internal team, etc.)"
• "Is this a new thing or improving something existing?"

```

Based on answers, determine the PROJECT TYPE:

• Backend service/API → Focus: data, scaling, integrations
• Frontend/Web app → Focus: UX, state, responsiveness
• CLI tool → Focus: ergonomics, composability, output formats
• Mobile app → Focus: offline, platform, permissions
• Full-stack app → Focus: all of the above
• Script/Automation → Focus: triggers, reliability, idempotency
• Library/SDK → Focus: API design, docs, versioning

Phase 2: Category-by-Category Deep Dive

Work through relevant categories IN ORDER. For each category:

1. Ask 2-4 questions using AskUserQuestion
2. Detect uncertainty - if user seems unsure, offer research
3. Educate when needed - don't let them make uninformed decisions
4. Track decisions - update your internal state

#### Category A: Problem & Goals

Questions to explore:

• What's the current pain point? How do people solve it today?
• What does success look like? How will you measure it?
• Who are the stakeholders beyond end users?
• What happens if this doesn't get built?

Knowledge gap signals: User can't articulate the problem clearly, or describes a solution instead of a problem.

#### Category B: User Experience & Journey

Questions to explore:

• Walk me through: a user opens this for the first time. What do they see? What do they do?
• What's the core action? (The one thing users MUST be able to do)
• What errors can happen? What should users see when things go wrong?
• How technical are your users? (Power users vs. novices)

Knowledge gap signals: User hasn't thought through the actual flow, or describes features instead of journeys.

#### Category C: Data & State

Questions to explore:

• What information needs to be stored? Temporarily or permanently?
• Where does data come from? Where does it go?
• Who owns the data? Are there privacy/compliance concerns?
• What happens to existing data if requirements change?

Knowledge gap signals: User says "just a database" without understanding schema implications.

#### Category D: Technical Landscape

Questions to explore:

• What existing systems does this need to work with?
• Are there technology constraints? (Language, framework, platform)
• What's your deployment environment? (Cloud, on-prem, edge)
• What's the team's technical expertise?

Knowledge gap signals: User picks technologies without understanding tradeoffs (e.g., "real-time with REST", "mobile with React").

Research triggers:

• "I've heard X is good" → Research X vs alternatives
• "We use Y but I'm not sure if..." → Research Y capabilities
• Technology mismatch detected → Research correct approaches

#### Category E: Scale & Performance

Questions to explore:

• How many users/requests do you expect? (Now vs. future)
• What response times are acceptable?
• What happens during traffic spikes?
• Is this read-heavy, write-heavy, or balanced?

Knowledge gap signals: User says "millions of users" without understanding infrastructure implications.

#### Category F: Integrations & Dependencies

Questions to explore:

• What external services does this need to talk to?
• What APIs need to be consumed? Created?
• Are there third-party dependencies? What's the fallback if they fail?
• What authentication/authorization is needed for integrations?

Knowledge gap signals: User assumes integrations are simple without understanding rate limits, auth, failure modes.

#### Category G: Security & Access Control

Questions to explore:

• Who should be able to do what?
• What data is sensitive? PII? Financial? Health?
• Are there compliance requirements? (GDPR, HIPAA, SOC2)
• How do users authenticate?

Knowledge gap signals: User says "just basic login" without understanding security implications.

#### Category H: Deployment & Operations

Questions to explore:

• How will this be deployed? By whom?
• What monitoring/alerting is needed?
• How do you handle updates? Rollbacks?
• What's your disaster recovery plan?

Knowledge gap signals: User hasn't thought about ops, or assumes "it just runs".

Phase 3: Research Loops

When you detect uncertainty or knowledge gaps:

```

AskUserQuestion(

question: "You mentioned wanting real-time updates. There are several approaches with different tradeoffs. Would you like me to research this before we continue?",

options: [

{label: "Yes, research it", description: "I'll investigate options and explain the tradeoffs"},

{label: "No, I know what I want", description: "Skip research, I'll specify the approach"},

{label: "Tell me briefly", description: "Give me a quick overview without deep research"}

]

)

```

If user wants research:

1. Spawn an oracle agent or use WebSearch/WebFetch
2. Gather relevant information
3. Summarize findings in plain language
4. Return with INFORMED follow-up questions

Example research loop:

```

User: "I want real-time updates"

You: [Research WebSockets vs SSE vs Polling vs WebRTC]

You: "I researched real-time options. Here's what I found:

- WebSockets: Best for bidirectional, but requires sticky sessions

- SSE: Simpler, unidirectional, works with load balancers

- Polling: Easiest but wasteful and not truly real-time

Given your scale expectations of 10k users, SSE would likely work well.

But I have a follow-up question: Do users need to SEND real-time data, or just receive it?"

```

Phase 4: Conflict Resolution

When you discover conflicts or impossible requirements:

```

AskUserQuestion(

question: "I noticed a potential conflict: You want [X] but also [Y]. These typically don't work together because [reason]. Which is more important?",

options: [

{label: "Prioritize X", description: "[What you lose]"},

{label: "Prioritize Y", description: "[What you lose]"},

{label: "Explore alternatives", description: "Research ways to get both"}

]

)

```

Common conflicts to watch for:

• "Simple AND feature-rich"
• "Real-time AND cheap infrastructure"
• "Highly secure AND frictionless UX"
• "Flexible AND performant"
• "Fast to build AND future-proof"

Phase 5: Completeness Check

Before writing the spec, verify you have answers for:

```markdown

Problem Definition

• [ ] Clear problem statement
• [ ] Success metrics defined
• [ ] Stakeholders identified

User Experience

• [ ] User journey mapped
• [ ] Core actions defined
• [ ] Error states handled
• [ ] Edge cases considered

Technical Design

• [ ] Data model understood
• [ ] Integrations specified
• [ ] Scale requirements clear
• [ ] Security model defined
• [ ] Deployment approach chosen

Decisions Made

• [ ] All tradeoffs explicitly chosen
• [ ] No "TBD" items remaining
• [ ] User confirmed understanding

```

If anything is missing, GO BACK and ask more questions.

Phase 6: Spec Generation

Only after completeness check passes:

1. Summarize what you learned:

```

"Before I write the spec, let me confirm my understanding:

You're building [X] for [users] to solve [problem].

The core experience is [journey].

Key technical decisions:

- [Decision 1 with rationale]

- [Decision 2 with rationale]

Is this accurate?"

```

1. Generate the spec to thoughts/shared/specs/YYYY-MM-DD-.md:

```markdown

# [Project Name] Specification

[2-3 sentences: what, for whom, why]

[The problem this solves, current pain points, why now]

[Measurable outcomes that define success]

[Who uses this, their technical level, their goals]

[Step-by-step flow of the core experience]

Must Have (P0)

• [Requirement with acceptance criteria]

Should Have (P1)

• [Requirement with acceptance criteria]

Nice to Have (P2)

• [Requirement with acceptance criteria]

Data Model

[Key entities and relationships]

System Components

[Major components and their responsibilities]

Integrations

[External systems and how we connect]

Security Model

[Auth, authorization, data protection]

• Performance: [specific metrics]
• Scalability: [expected load]
• Reliability: [uptime requirements]
• Security: [compliance, encryption]

[Explicitly what we're NOT building]

[Technical details to resolve during implementation]

[Summary of research conducted during discovery]

```

Question Phrasing

• Bad: "What database do you want?" (assumes they know databases)
• Good: "What kind of data will you store, and how often will it be read vs written?"

Option Design

Always include options that acknowledge uncertainty:

```

options: [

{label: "Option A", description: "Clear choice with implications"},

{label: "Option B", description: "Alternative with different tradeoffs"},

{label: "I'm not sure", description: "Let's explore this more"},

{label: "Research this", description: "I'll investigate and come back"}

]

```

Multi-select for Features

```

AskUserQuestion(

question: "Which of these capabilities do you need?",

multiSelect: true,

options: [...]

)

```

Watch for these signals:

| Signal | What to do |

|--------|------------|

| "I think..." or "Maybe..." | Probe deeper, offer research |

| "That sounds good" (to your suggestion) | Verify they understand implications |

| "Just simple/basic X" | Challenge - define what simple means |

| Technology buzzwords without context | Ask what they think it does |

| Conflicting requirements | Surface the conflict explicitly |

| "Whatever is standard" | Explain there's no universal standard |

| Long pauses / short answers | They might be overwhelmed - simplify |

```

You: "What problem are you trying to solve?"

User: "I want to build an app where people can share recipes"

You: [AskUserQuestion: "Who specifically will use this? What's their cooking level?"]

User: "Home cooks, beginners to intermediate"

You: [AskUserQuestion: "Walk me through: someone opens your app for the first time. What do they see? What do they do first?"]

User: "Um, I guess they see recipes? And they can search?"

You: [Detected uncertainty in UX]

"It sounds like the user journey isn't fully mapped yet. Let me help with that.

[AskUserQuestion: 'What's the ONE thing a user should accomplish in their first 2 minutes?'

Options:

- Find and save a recipe

- Create their first recipe

- Browse trending recipes

- Set up their taste preferences

- Research this (I'll look at successful recipe apps)]"

User: "Research this - what do successful apps do?"

You: [Spawn research agent or WebSearch]

[Returns with findings from AllRecipes, Tasty, Paprika, etc.]

You: "I researched successful recipe apps. Here's what I found:

- Most start with a quick 'taste quiz' to personalize

- The core action is 'save recipe to collection'

- Discovery is usually browse-first, search-second

Given this, let's refine: [AskUserQuestion with informed options]"

[Continue until all categories are covered with sufficient depth]

```

1. Never write the spec after just 3-5 questions - that produces slop
2. Minimum 10-15 questions across categories for any real project
3. At least 2 questions per relevant category
4. At least 1 research loop for any non-trivial project
5. Always do a completeness check before writing
6. Summarize understanding before finalizing

Technical User

• Can skip some education
• Still probe for assumptions ("You mentioned Kubernetes - have you considered the operational complexity?")
• Focus more on tradeoffs than explanations

Non-Technical User

• More education needed
• Use analogies ("Think of an API like a waiter - it takes your order to the kitchen")
• Offer more research options
• Don't overwhelm with technical options

User in a Hurry

• Acknowledge time pressure
• Prioritize: "If we only have 10 minutes, let's focus on [core UX and data model]"
• Note what wasn't covered as risks

After spec is written, ALWAYS ask about next steps:

```

AskUserQuestion(

question: "Spec created at thoughts/shared/specs/YYYY-MM-DD-.md. How would you like to proceed?",

options: [

{label: "Start implementation now", description: "I'll begin implementing the spec in this session"},

{label: "Review spec first", description: "Read the spec and come back when ready"},

{label: "Plan implementation", description: "Create a detailed implementation plan with tasks"},

{label: "Done for now", description: "Save the spec, I'll implement later"}

]

)

```

If "Start implementation now":

```

Say: "To implement this spec, say: 'implement the spec'

This will:

1. Activate the spec context (drift prevention enabled)
2. Inject requirements before each edit
3. Checkpoint every 5 edits for alignment
4. Validate acceptance criteria before finishing"

```

If "Plan implementation":

```

Spawn plan-agent or invoke /create_plan with the spec path

```

If "Review spec first" or "Done for now":

```

Say: "Spec saved. When ready, say 'implement the spec' to begin.

The spec includes:

• Problem statement
• User journeys
• Technical requirements
• Acceptance criteria

All of these will be used for drift prevention during implementation."

```