QUICK DISCOVERY MODE

I'll ask rapid-fire questions. Answer with:
  • Y/N for yes/no
  • Skip to use defaults
  • Expand to dive deeper on any topic

Ready? Let's go...

┌─────────────────────────────────────────────────────────────────┐
│  QUICK DISCOVERY CHECKLIST                                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  VISION (30 seconds)                                            │
│  ├─ One-line description: _______________________               │
│  └─ Primary user: _______________________                       │
│                                                                 │
│  SCOPE (Y/N/Skip for each)                                      │
│  ├─ Backend API?          [Y/N]                                 │
│  ├─ Frontend UI?          [Y/N]                                 │
│  ├─ Database?             [Y/N]                                 │
│  ├─ Authentication?       [Y/N]                                 │
│  ├─ External APIs?        [Y/N]                                 │
│  └─ Mobile?               [Y/N]                                 │
│                                                                 │
│  LAYER (pick one)                                               │
│  └─ L0/L1/L2/L3/L4/L5?    [___]                                 │
│                                                                 │
│  CONSTRAINTS (Y/N/Skip)                                         │
│  ├─ High performance?     [Y/N] → If Y: latency target? ___    │
│  ├─ Security critical?    [Y/N] → If Y: compliance? ___        │
│  ├─ High availability?    [Y/N] → If Y: SLA target? ___        │
│  └─ Edge deployment?      [Y/N]                                 │
│                                                                 │
│  SOFTWARE POTENTIAL (Y/N/Future/Skip)                           │
│  ├─ Public API?           [Y/N/F]                               │
│  ├─ Plugin system?        [Y/N/F]                               │
│  ├─ Multi-tenant?         [Y/N/F]                               │
│  ├─ Self-hosted option?   [Y/N/F]                               │
│  └─ ML/AI features?       [Y/N/F]                               │
│                                                                 │
│  PIPELINE CONFIG                                                │
│  ├─ Skip deployment phase? [Y/N] (component mode)               │
│  ├─ Skip E2E tests?        [Y/N] (tested elsewhere)             │
│  └─ Generate tasks.json?   [Y/N]                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

{
  "pipeline_config": {
    "mode": "component",
    "skip_phases": [8, 8.5],
    "optional_phases": [7],
    "focus_areas": ["interface_contracts", "unit_tests", "documentation"],
    "deployment_venue": "external",
    "e2e_venue": "integration_repo"
  }
}

Before we dive in, would you like me to research the landscape?

I can look up:
  • Competitors - pricing, features, differentiators
  • Technical patterns - how others solve similar problems
  • Market data - size, trends, opportunities

This helps inform our decisions but won't drive requirements.
Your vision stays primary.

Say "research competitors" or "skip research" to continue.

{
  "version": "2.0",
  "status": "in_progress",
  "current_stage": "0.1",
  "stages": {
    "0.1": { "name": "Artifact Collection", "status": "pending", "started_at": null, "completed_at": null },
    "0.2": { "name": "Project Context", "status": "pending", "started_at": null, "completed_at": null },
    "0.2.5": { "name": "User Discovery", "status": "pending", "started_at": null, "completed_at": null },
    "0.3": { "name": "Scope Bounding", "status": "pending", "started_at": null, "completed_at": null },
    "0.4": { "name": "Input/Output Definition", "status": "pending", "started_at": null, "completed_at": null },
    "0.4.5": { "name": "Dependency Documentation Capture", "status": "pending", "started_at": null, "completed_at": null },
    "0.5": { "name": "Constraint Elicitation", "status": "pending", "started_at": null, "completed_at": null },
    "0.6": { "name": "Requirements Discovery", "status": "pending", "started_at": null, "completed_at": null },
    "0.6.5": { "name": "Architecture Design", "status": "pending", "started_at": null, "completed_at": null, "human_approved": false },
    "0.7": { "name": "PRD Synthesis", "status": "pending", "started_at": null, "completed_at": null },
    "0.8": { "name": "Strategic Alignment", "status": "pending", "started_at": null, "completed_at": null }
  },
  "artifacts_collected": [],
  "project_type": null,
  "layer_assignment": null,
  "personas": [],
  "software_potential": null,
  "mvp_scope": null
}

.discovery/
├── artifacts/
│   ├── existing-prds/
│   ├── architecture/
│   ├── interfaces/
│   ├── existing-code/
│   ├── compliance/
│   └── research/
├── scope/
├── discovery-state.json
└── discovery-log.md

PHASE 2: PROJECT DISCOVERY

I'll guide you through defining your project requirements. We'll cover:

  Stage 2.1:   Artifact Collection     (gather context + web research)
  Stage 2.2:   Project Context         (understand positioning)
  Stage 2.2.5: User Discovery          (personas, journeys, pain points)
  Stage 2.3:   Scope Bounding          (define boundaries + software potential)
  Stage 2.4:   Input/Output Definition (specify interfaces + fetch API docs)
  Stage 2.4.5: Dependency Docs Capture (version-pinned API documentation)
  Stage 2.5:   Constraint Elicitation  (non-negotiables + benchmarks)
  Stage 2.6:   Requirements Discovery  (define what system does)
  Stage 2.6.5: Architecture Design     (C4 diagrams + human approval) ← MANDATORY
  Stage 2.7:   PRD Synthesis           (generate PRD from discovery artifacts)
  Stage 2.8:   Strategic Alignment     (business validation + MVP scope)

I have full internet access — I can research competitors, fetch API
docs, look up benchmarks, and analyze similar projects as we go.

This process ensures we're building the RIGHT thing (Stages 2.1-2.8)
before we build it RIGHT (Phases 3-12).

Time estimate: 45-120 minutes

You can pause anytime and resume later.

Ready to begin? Let's start with Stage 2.1: Artifact Collection.

Persona: [Name]
Role: [Job title/role]
Goals:
  - [Primary goal]
  - [Secondary goal]
Pain Points:
  - [Current frustration 1]
  - [Current frustration 2]
Context: [When/where/how they'd use this]
Quote: "[Something this persona might say about the problem]"

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Awareness  │────▶│   First Use │────▶│  Regular Use│────▶│   Advocacy  │
│  How they   │     │  Onboarding │     │  Core value │     │  Sharing    │
│  find us    │     │  experience │     │  delivery   │     │  with others│
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

software_potential:
  # API & Extensibility
  api_extensibility:
    public_api: [In v1 / Future / Never / TBD]
    webhook_support: [In v1 / Future / Never / TBD]
    developer_sdk: [In v1 / Future / Never / TBD]
    plugin_system: [In v1 / Future / Never / TBD]
    custom_integrations: [In v1 / Future / Never / TBD]

  # Deployment Models
  deployment_models:
    saas_hosted: [In v1 / Future / Never / TBD]
    self_hosted: [In v1 / Future / Never / TBD]
    edge_deployment: [In v1 / Future / Never / TBD]
    air_gapped_offline: [In v1 / Future / Never / TBD]
    multi_region: [In v1 / Future / Never / TBD]

  # Multi-Tenancy & Scale
  multi_tenancy:
    shared_infrastructure: [In v1 / Future / Never / TBD]
    tenant_isolation: [In v1 / Future / Never / TBD]
    custom_domains: [In v1 / Future / Never / TBD]
    white_label: [In v1 / Future / Never / TBD]

  # Data & Intelligence
  data_strategy:
    analytics_dashboard: [In v1 / Future / Never / TBD]
    data_export: [In v1 / Future / Never / TBD]
    ml_ai_features: [In v1 / Future / Never / TBD]
    data_marketplace: [In v1 / Future / Never / TBD]

  # Platform Evolution
  platform_potential:
    app_marketplace: [In v1 / Future / Never / TBD]
    partner_ecosystem: [In v1 / Future / Never / TBD]
    developer_community: [In v1 / Future / Never / TBD]
    certification_program: [In v1 / Future / Never / TBD]

  # Monetization
  monetization:
    subscription: [In v1 / Future / Never / TBD]
    usage_based: [In v1 / Future / Never / TBD]
    freemium: [In v1 / Future / Never / TBD]
    enterprise_licensing: [In v1 / Future / Never / TBD]
    marketplace_revenue: [In v1 / Future / Never / TBD]

# docs/discovery/dependencies/dependency-manifest.yaml
dependencies:
  host_systems:
    - name: "macOS"
      version: "15.1+"
      relevant_apis: ["Accessibility", "Keychain", "Notifications"]

  runtime_platforms:
    - name: "Node.js"
      version: "20.x LTS"
      relevant_features: ["ESM modules", "fetch API", "crypto"]

  libraries:
    - name: "axios"
      version: "1.6.0"  # EXACT version, not ^1.6.0
      usage: "HTTP client for API calls"

    - name: "react"
      version: "18.2.0"
      usage: "UI framework"

  cloud_services:
    - name: "AWS Lambda"
      runtime: "nodejs20.x"
      relevant_apis: ["Invocation", "Layers", "Environment"]

  external_apis:
    - name: "Stripe"
      api_version: "2024-11-20"
      endpoints_used: ["PaymentIntents", "Customers"]

  messaging_systems:
    - name: "Redis"
      version: "7.2"
      usage: "Pub/Sub, Caching"

For each dependency:
1. Identify official documentation URL
2. Fetch documentation for EXACT version (not latest)
3. Extract relevant API surface:
   - Function/method signatures
   - Request/response formats
   - Error codes and handling
   - Rate limits and quotas
   - Authentication requirements
   - Known issues/edge cases
4. Store in structured format
5. Note any version-specific behavior changes

docs/discovery/dependencies/
├── dependency-manifest.yaml      # Master list linking deps to docs
├── host-systems/
│   ├── macos-15.1-accessibility.md
│   └── macos-15.1-keychain.md
├── runtimes/
│   └── nodejs-20.x-api-surface.md
├── libraries/
│   ├── axios-1.6.0/
│   │   ├── api-reference.md      # Core API surface
│   │   ├── error-handling.md     # Error types and codes
│   │   └── breaking-changes.md   # Changes from previous versions
│   └── react-18.2.0/
│       ├── hooks-reference.md
│       └── concurrent-features.md
├── cloud-services/
│   └── aws-lambda-nodejs20/
│       ├── runtime-api.md
│       ├── limits-quotas.md
│       └── error-codes.md
├── external-apis/
│   └── stripe-2024-11-20/
│       ├── payment-intents.md
│       └── error-codes.md
└── messaging/
    └── redis-7.2/
        ├── commands-reference.md
        └── pubsub-patterns.md

# Version-Specific Notes

## axios 1.6.0
- **Breaking Change**: Error response structure changed from 1.5.x
- **New**: `formToJSON` utility added
- **Gotcha**: Default timeout is now `0` (infinite) not `10000`

## macOS 15.1 Accessibility
- **Requirement**: App must be added to System Preferences > Privacy > Accessibility
- **Gotcha**: Silent failure if not authorized - no error thrown
- **Detection**: Use `AXIsProcessTrusted()` to check

## Node.js 20.x
- **New**: Native `fetch()` API now stable
- **Gotcha**: `fetch()` doesn't throw on 4xx/5xx - must check `response.ok`
- **Breaking**: `--experimental-modules` no longer needed

# Dependency Contract Summary

This document summarizes the API contracts that implementation must follow.
Use this during code review and testing validation.

## HTTP Client (axios 1.6.0)

### Request Pattern
```javascript
const response = await axios.get(url, {
  timeout: 5000,  // MUST set - default is infinite
  validateStatus: (status) => status < 500  // Handle 4xx as success
});

try {
  await axios.post(url, data);
} catch (error) {
  if (error.response) {
    // Server responded with 4xx/5xx
    // error.response.data, error.response.status
  } else if (error.request) {
    // Request made but no response (network error)
  } else {
    // Request setup error
  }
}

// MUST check before using accessibility APIs
if !AXIsProcessTrusted() {
  // Prompt user to grant access
  let options = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true]
  AXIsProcessTrustedWithOptions(options as CFDictionary)
}

**Research Actions:**

| Question | Research Action |
|----------|-----------------|
| "What version of X should we use?" | Compare latest stable vs LTS, check compatibility |
| "What's different in X version Y?" | Fetch changelog, migration guide |
| "What are common issues with X?" | Search GitHub issues, Stack Overflow |
| "What permissions does X need?" | Fetch platform-specific requirements |

**Completion Criteria:**
- [ ] All dependencies from PRD Section 2 enumerated in manifest
- [ ] Version-specific documentation captured for each dependency
- [ ] Host system API requirements documented
- [ ] Breaking changes and gotchas noted
- [ ] Contract summary created for implementation reference
- [ ] User confirms dependency documentation is complete

**Output Files:**
- `docs/discovery/dependencies/dependency-manifest.yaml`
- `docs/discovery/dependencies/*/` (per-dependency docs)
- `docs/discovery/dependencies/version-notes.md`
- `docs/discovery/dependencies/contract-summary.md`

---

## Stage 2.5: Constraint Elicitation

**Goal:** Document non-negotiable requirements.

**Walk through four categories:**

### Performance Constraints
- Latency requirements (target, max, P99)
- Throughput requirements
- Memory limits
- CPU/GPU requirements
- Startup time

### Security Constraints
- Network model (traditional, zero trust, air-gapped)
- Authentication requirements
- Data classification
- Compliance frameworks
- Encryption requirements

### Reliability Constraints
- Availability target
- Failure mode (fail-fast, fail-safe, graceful)
- Recovery time objective
- Redundancy requirements

### Compliance Constraints
- Industry standards
- Regulatory requirements
- Audit requirements

**Web Research for Constraints:**

When user is uncertain, **proactively research benchmarks**:

| Constraint Type | Research Action |
|-----------------|-----------------|
| Latency targets | Search for industry benchmarks (e.g., "e-commerce API latency benchmarks") |
| Availability | Look up SLA standards for similar services |
| Compliance | Fetch framework requirements (SOC2, HIPAA, PCI-DSS, GDPR) |
| Security standards | Research OWASP, NIST, CIS benchmarks |
| Performance | Find case studies from similar-scale systems |

**Offer research when user says "I don't know":**
- "I can look up typical [latency/availability/etc.] requirements for [industry/project type]. Want me to?"
- "Should I research what [compliance framework] specifically requires?"
- "I can find benchmarks from similar projects. Interested?"

**Save research to:** `.discovery/artifacts/research/benchmarks.md`

**For any "I don't know" responses:**
- Offer to research benchmarks
- Suggest reasonable defaults based on research
- Mark as "TBD" if user prefers

**Generate:** `.discovery/scope/constraints.yaml`

**Completion criteria:**
- All constraint categories addressed
- Benchmarks researched (if requested)
- User confirms constraints summary
- constraints.yaml created

## Stage 2.6: Requirements Discovery

**Goal:** Define functional requirements in EARS format.

**EARS Format:**

**Process:**
1. Start with core functionality based on project description
2. Propose requirements from artifacts (if any)
3. Ask clarifying questions
4. For each requirement:
   - State in EARS format
   - Assign ID (R_XXX)
   - Ask user to Accept / Modify / Reject

**Requirement categories to cover:**
- Core functionality
- Error handling
- Performance (derived from constraints)
- Security (derived from constraints)
- Observability
- Integration points

**Completion criteria:**
- All major functional areas covered
- Each requirement in EARS format with ID
- User confirms requirements are complete

## Stage 2.6.5: Architecture Design (NEW - MANDATORY)

**Goal:** Create C4 architecture diagrams and get human approval BEFORE PRD synthesis.

> **Why This Stage Matters:**
> Architecture diagrams force explicit thinking about system structure, dependencies,
> and data flows. This prevents "discovery drift" where research is gathered but
> not incorporated into the final design.

**Step 1: Initialize Discovery Structure**

If `docs/discovery/` doesn't exist, run initialization:
```bash
scripts/init-discovery.sh
# OR
.claude/scripts/init-discovery.sh

docs/discovery/
├── research/           <- Web research findings (from earlier stages)
│   ├── technology-stack.md
│   ├── competitor-analysis.md
│   ├── best-practices.md
│   └── sources.md
├── diagrams/           <- C4 architecture diagrams (create in this stage)
│   ├── context.mmd
│   ├── container.mmd
│   ├── dataflow.mmd
│   └── deployment.mmd
├── decisions/          <- Architecture Decision Records
│   └── ADR-000-template.md
└── agreements/         <- Human approval tracking
    ├── architecture-review.md
    └── approval-log.md

RESEARCH SUMMARY FOR ARCHITECTURE DESIGN

Technology Stack Research:
  - [Summary from technology-stack.md]
  - Key sources: [list URLs]

Competitor Analysis:
  - [Summary from competitor-analysis.md]
  - Insights: [what we learned]

Best Practices:
  - [Summary from best-practices.md]
  - Patterns to adopt: [list]

This research will inform the following architecture decisions...

Based on our research and requirements, here's the System Context:

```mermaid
flowchart TB
    subgraph boundary ["System Boundary"]
        System["🖥️ [System Name]<br/><i>[Brief description]</i>"]
    end

    User["👤 [Primary User]<br/><i>[Role]</i>"]
    Admin["👤 [Admin]<br/><i>[Role]</i>"]

    ExtAPI["🌐 [External API]<br/><i>[What it provides]</i>"]

    User -->|"[Interaction]"| System
    Admin -->|"[Interaction]"| System
    System -->|"[Protocol]"| ExtAPI

**Step 4: Create ADR for Major Decisions**

For significant architectural choices, create ADRs:
- Technology stack selections
- Framework choices
- Database selection
- Integration patterns

Save to: `docs/discovery/decisions/ADR-001-[topic].md`

**Step 5: Get Human Approval (GATE)**

Present all diagrams and ask for explicit approval:

**DO NOT proceed to Stage 2.7 until user says "Architecture approved"**

**Completion criteria:**
- docs/discovery/ structure exists
- All 4 C4 diagrams created in docs/discovery/diagrams/
- Research summarized and incorporated
- At least one ADR for major technology choice
- User explicitly approved architecture
- Approval logged in docs/discovery/agreements/approval-log.md

---

## Stage 2.7: PRD Synthesis

**Goal:** Generate the final PRD, deeply incorporating ALL discovery artifacts.

> **CRITICAL:** The PRD must reference and incorporate all research and diagrams
> from docs/discovery/. This is NOT optional.

**Pre-Synthesis Checklist (MANDATORY):**

Before generating PRD, verify you have READ:
- [ ] `docs/discovery/research/technology-stack.md`
- [ ] `docs/discovery/research/competitor-analysis.md`
- [ ] `docs/discovery/research/best-practices.md`
- [ ] `docs/discovery/research/sources.md`
- [ ] `docs/discovery/diagrams/context.mmd`
- [ ] `docs/discovery/diagrams/container.mmd`
- [ ] `docs/discovery/diagrams/dataflow.mmd`
- [ ] `docs/discovery/diagrams/deployment.mmd`
- [ ] `docs/discovery/decisions/ADR-*.md` (all ADRs)

If ANY of these files don't exist, STOP and complete Stage 2.6.5 first.

**Process:**
1. Read ALL docs/discovery/* artifacts
2. Compile all discovery outputs from previous stages
3. Generate PRD using Template v2.0 structure
4. **Embed diagrams in Section 5 (System Architecture)**
5. **Reference research in Section 17 (Research References)**
6. Populate all 19 sections
7. Present summary to user

**PRD Sections to generate:**
0. Vision & Problem Statement (from Stage 0.2.5)
1. Architectural Layer Assignment
2. Dependency Declaration
3. Interface Contract Summary
4. Executive Summary
5. System Architecture
6. Feature Requirements (from Stage 0.6) + Anti-Requirements
7. Non-Functional Requirements (from Stage 0.5)
8. Code Structure
9. TDD Implementation Guide
10. Integration Testing
11. Documentation Requirements
12. Operational Readiness
13. Compliance & Audit
14. Migration & Rollback
15. Risk & Assumptions
16. Success Metrics
17. Task Decomposition Guidance
18. Future Potential & Evolution (from Stage 0.3 software potential)
Appendices A-E

**Present to user:**

**Completion criteria:**
- PRD generated at docs/PRD.md
- User has reviewed initial draft

## Stage 2.8: Strategic Alignment (NEW)

**Goal:** Validate the PRD against business objectives before proceeding to execution.

**Why this matters:** Technical requirements should serve business goals. This gate ensures we're building the right thing before we build it right.

### Step 1: Business Model Validation

Ask: "How does this software create and capture value?"

| Question | Answer |
|----------|--------|
| Who pays? | [Customer / Advertiser / Enterprise / N/A] |
| How do they pay? | [Subscription / Usage / One-time / Free] |
| What's the unit economics? | [Cost to serve vs. revenue per user] |
| What's the growth model? | [Viral / Sales / Content / Product-led] |

### Step 2: Stakeholder Alignment

Ask: "Who needs to approve or be informed about this project?"

| Stakeholder | Interest | Influence | Status |
|-------------|----------|-----------|--------|
| [Name/Role] | [Their goals] | [High/Medium/Low] | [Approve/Inform/Consult] |

### Step 3: MVP Definition

Ask: "What's the smallest version that delivers value?"

### Step 4: Success Criteria Review

Review success metrics from PRD Section 0.5:

| Metric | Target | Realistic? | Measurable? | Aligned with Business? |
|--------|--------|------------|-------------|------------------------|
| [Metric 1] | [Target] | [Y/N] | [Y/N] | [Y/N] |
| [Metric 2] | [Target] | [Y/N] | [Y/N] | [Y/N] |

### Step 5: Risk Acknowledgment

Review top risks from discovery:

| Risk | Impact | Probability | Mitigation | Accepted? |
|------|--------|-------------|------------|-----------|
| [Risk 1] | [H/M/L] | [H/M/L] | [Strategy] | [Y/N] |
| [Risk 2] | [H/M/L] | [H/M/L] | [Strategy] | [Y/N] |

### Step 6: Final Approval

Present summary:

**Generate:** `.discovery/strategic-alignment.yaml`

**Completion criteria:**
- Business model validated
- Stakeholders identified
- MVP scope confirmed
- Success criteria reviewed
- Risks acknowledged
- User gives final approval

## Commands

Handle these commands during discovery:

| Command | Action |
|---------|--------|
| `discovery status` | Show current stage and progress |
| `discovery pause` | Save state and pause |
| `discovery resume` | Resume from saved state |
| `discovery restart` | Start over (keeps artifacts) |
| `skip` | Skip current question |
| `back` | Return to previous question |
| `help` | Show help for current stage |
| `example` | Show example for current question |

## Transition to Phase 3

When user approves PRD:
1. Update discovery state to complete
2. Create `.claude/.signals/phase2-complete.json`
3. Transition to Phase 3 (PRD Validation)

## Error Recovery

If user seems stuck:
- Offer to show an example
- Offer to skip and return later
- Suggest breaking down the question

If artifacts fail to load:
- Log error
- Continue without that artifact
- Note gap in discovery-log.md

## Output Files