Discovery Interview

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:

## Completeness Checklist

### 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?"
   

2. Generate the spec to thoughts/shared/specs/YYYY-MM-DD-<name>.md:

# [Project Name] Specification

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

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

## Success Criteria
[Measurable outcomes that define success]

## User Personas
[Who uses this, their technical level, their goals]

## User Journey
[Step-by-step flow of the core experience]

## Functional Requirements
### Must Have (P0)
- [Requirement with acceptance criteria]

### Should Have (P1)
- [Requirement with acceptance criteria]

### Nice to Have (P2)
- [Requirement with acceptance criteria]

## Technical Architecture
### 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]

## Non-Functional Requirements
- Performance: [specific metrics]
- Scalability: [expected load]
- Reliability: [uptime requirements]
- Security: [compliance, encryption]

## Out of Scope
[Explicitly what we're NOT building]

## Open Questions for Implementation
[Technical details to resolve during implementation]

## Appendix: Research Findings
[Summary of research conducted during discovery]

AskUserQuestion Best Practices

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: