Phase2 Discovery

Phase 2: Project Discovery Skill

Metadata

• skill_name: phase2-discovery
• activation_code: PHASE2_DISCOVERY_V1
• version: 1.0.0
• category: discovery
• phase: 2

Description

Interactive project discovery orchestrator. Guides users through artifact collection, scope definition, and PRD generation through a conversational seven-stage process.

Activation Criteria

• User says "begin project discovery", "start discovery", or "discover"
• User opens a project with .discovery/discovery-state.json showing incomplete status
• User says "resume discovery"
• Before any Phase 3+ work when no PRD exists

Discovery Modes

Quick Mode (Express Discovery)

For users who already know what they want to build. Uses rapid yes/no questions instead of deep exploration.

Activation: "quick discovery", "express discovery", "fast PRD"

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 Mode Flow:

┌─────────────────────────────────────────────────────────────────┐
│  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]                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Time: 5-10 minutes (vs 45-120 for full discovery)

Component Mode

For building components that integrate into a larger system. Skips deployment and certain operational phases.

Activation: "component mode", "library mode", "building a component"

What's different:

• Skips Phase 8 (Deployment) - deployment happens at system level
• Skips E2E user workflows - tested at integration level
• Focuses on interface contracts and API design
• Emphasizes testability and documentation

Pipeline ends at: Phase 6 (Integration Testing) or Phase 7 (if E2E included)

{
  "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"
  }
}

Full Mode (Default)

Complete 9-stage discovery with deep exploration of each area. Best for:

• Greenfield projects
• Complex systems
• When you're not sure what to build

Web Research Integration

This skill integrates with the Web Researcher skill for structured external research using Claude Code's built-in WebSearch and WebFetch tools.

Research Prompt

At the start of discovery, offer research:

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.

When to Offer Research

Research Output Integration

Web research results are saved to .research/ and can feed into PRD:

• Section 3 (Market Context): Competitor landscape, market size
• Section 5 (Anti-Requirements): "Unlike X, we won't..."
• Section 8 (Architecture): Technical pattern recommendations

Note: Research-sourced additions get -0.15 confidence penalty with Plan Guardian.

Internet-Enabled Discovery

This skill has full internet access. Leverage this throughout the discovery process:

Available Research Capabilities

Proactive Research Opportunities

During discovery, proactively offer to research:

1. Stage 0.1 (Artifacts): "Would you like me to find similar open-source projects or competitor products for reference?"

2. Stage 0.2 (Context): "I can research common architectural patterns for [project type]. Want me to look that up?"

3. Stage 0.3 (Scope): "Should I check what features similar products typically include?"

4. Stage 0.4 (I/O): "I can fetch the API documentation for [mentioned service]. Would that help?"

5. Stage 0.5 (Constraints): "Want me to look up industry benchmarks for [performance/security] requirements?"

6. Stage 0.6 (Requirements): "I can research how similar systems handle [specific functionality]. Interested?"

Research Output

When conducting research, save findings to .discovery/artifacts/research/:

• competitors.md — Competitive analysis
• api-specs/ — Downloaded API documentation
• best-practices.md — Industry best practices
• benchmarks.md — Performance/security benchmarks
• technology-options.md — Technology comparison notes

Discovery State

Track progress in .discovery/discovery-state.json:

{
  "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
}

Starting Discovery

When user initiates discovery:

1. Check for existing state

   • If .discovery/discovery-state.json exists and is incomplete, offer to resume
   • Otherwise, create fresh discovery state

2. Create directory structure

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

3. Display welcome message

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.

Stage 2.1: Artifact Collection

Goal: Gather existing materials that provide context — both local files AND web resources.

Questions to ask:

1. "Do you have any existing materials to share that would help me understand your project?"

2. Present categories for local artifacts:

   • Parent or related PRDs (if part of larger system)
   • Architecture diagrams
   • Interface specifications (APIs, protocols)
   • Existing codebase (if improving existing code)
   • Compliance/regulatory documents
   • Research papers or whitepapers
   • Meeting notes or decision records

3. Offer web-based research:

   • "Would you like me to research similar projects or competitors online?"
   • "Are there any APIs or services you plan to integrate with? I can fetch their documentation."
   • "Should I look up any technical standards or compliance frameworks relevant to your project?"

4. For each artifact provided:

   • Copy to appropriate .discovery/artifacts/ subdirectory
   • Analyze and extract key information
   • Summarize findings to user

5. For web research conducted:

   • Save to .discovery/artifacts/research/
   • Summarize key findings
   • Note sources for traceability

6. If user says "none" or "skip":

   • Acknowledge greenfield project
   • Still offer: "Even without local artifacts, I can research similar projects online. Interested?"

Web Research Actions:

Completion criteria:

• User confirms all artifacts collected
• Web research completed (if requested)
• Summary of all artifacts displayed
• State updated with artifacts_collected list

Stage 2.2: Project Context

Goal: Understand project type and positioning.

Questions to ask:

1. "What type of project is this?"

   • Greenfield (new from scratch)
   • Brownfield (improving existing code)
   • Replacement (rewriting legacy system)
   • Integration (connecting existing systems)

2. If brownfield/replacement: "What's being kept vs. replaced?"

3. "Where does this fit architecturally?" (Explain L0-L5 layers)

   • L0: Primitives (math, types, no dependencies)
   • L1: Infrastructure (logging, config, networking)
   • L2: Spatial (coordinates, transforms)
   • L3: Processing (algorithms, data processing)
   • L4: Fusion (multi-source integration)
   • L5: Interface (APIs, user-facing)

4. "What systems does this depend on?" (upstream)

5. "What systems depend on this?" (downstream)

If artifacts include parent PRD:

• Extract positioning information automatically
• Confirm with user

Completion criteria:

• Project type determined
• Layer assignment confirmed
• Dependencies documented

Stage 2.2.5: User Discovery (NEW)

Goal: Understand who will use this and why, before defining scope.

Why this matters: Scope decisions should be driven by user needs, not technical convenience. This stage ensures we build the right thing for the right people.

Step 1: Identify User Types

Ask: "Who are the different types of people who will use this system?"

For each user type, capture:

• Role/title
• Primary goal with the system
• Technical sophistication level
• Frequency of use

Step 2: Create Primary Persona

Template:

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]"

Proactive Research:

• "Want me to research user behavior patterns for [this type of user]?"
• "I can look up UX best practices for [industry/domain]. Interested?"

Step 3: Map User Journey

For the primary persona, map their journey:

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

Ask at each stage:

• What are they trying to accomplish?
• What emotions are they feeling?
• What could go wrong?

Step 4: Identify Pain Points

Ask: "What's frustrating about how users solve this problem today?"

Categories:

• Time wasters
• Error-prone steps
• Missing information
• Context switching
• Waiting/delays

Step 5: Define Value Proposition

Help user articulate:

• Core benefit (primary value)
• Unique differentiator (why choose this)
• Proof points (how we demonstrate value)

Generate: .discovery/scope/personas.yaml, .discovery/scope/user-journey.md

Completion criteria:

• At least one primary persona defined
• User journey mapped for primary persona
• Top 3 pain points identified
• Value proposition articulated

Stage 2.3: Scope Bounding

Goal: Explicitly define what's IN and OUT of scope.

Ask about each component category:

Generate: .discovery/scope/boundaries.yaml

Software Potential Checklist (NEW)

After defining basic scope, explore future potential dimensions:

Ask: "Let's think about what this could become. For each dimension, tell me if it's relevant now, might be relevant later, or not applicable."

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]

Why this matters: Decisions made now affect future potential. Understanding future possibilities helps make better architectural choices today.

Proactive Research:

• "I can research how similar products evolved over time. Want me to look that up?"
• "Should I find examples of successful platform/ecosystem plays in this space?"

Generate: .discovery/scope/software-potential.yaml

Completion criteria:

• All categories addressed
• User confirms scope summary
• boundaries.yaml created
• software-potential.yaml created

Stage 2.4: Input/Output Definition

Goal: Precisely define system interfaces.

For INPUTS, ask:

• What data/requests does the system receive?
• Where does each input come from?
• What format (JSON, protobuf, binary, etc.)?
• What rate/frequency?

For OUTPUTS, ask:

• What data/responses does the system produce?
• Who/what consumes each output?
• What format?
• What rate/frequency?

Don't forget:

• Configuration inputs
• Metrics outputs
• Log outputs
• Event outputs

Web Research for Interfaces:

When user mentions an external service or API:

1. Offer to fetch documentation: "I can pull the API docs for [service]. Want me to?"
2. Look up OpenAPI/Swagger specs if available
3. Research common integration patterns for that service
4. Save specs to .discovery/artifacts/api-specs/

Generate: .discovery/scope/inputs.yaml, .discovery/scope/outputs.yaml

Completion criteria:

• All inputs documented with source, format, rate
• All outputs documented with consumer, format, rate
• External API specs fetched (if applicable)
• User confirms I/O summary

Stage 2.4.5: Dependency Documentation Capture (NEW - CRITICAL)

Goal: Capture version-specific documentation for ALL planned dependencies to enable contract-based validation.

Why This Stage Exists: Bugs often arise from misunderstanding how dependencies actually work at the exact version used. Generic web searches aren't enough - we need authoritative, version-pinned API documentation that can be validated against during implementation and testing.

Step 1: Enumerate All Dependencies

Compile a complete list from PRD Section 2 and discovered I/O:

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

Step 2: Fetch Version-Specific Documentation

For EACH dependency, capture authoritative documentation:

Documentation Capture Process:

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

Step 3: Create Structured Documentation Cache

Store in docs/discovery/dependencies/:

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

Step 4: Document Version-Specific Gotchas

Create docs/discovery/dependencies/version-notes.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

Step 5: Generate Contract Summary

Create docs/discovery/dependencies/contract-summary.md:

# 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
});

Error Handling Contract

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
  }
}

macOS Accessibility (15.1+)

Permission Check Contract

// 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:**

WHEN [trigger condition], the system SHALL [required behavior].

**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

This creates:

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

Step 2: Consolidate Research

Before creating diagrams, READ and summarize all research conducted:

1. Read .discovery/artifacts/research/* (older format)
2. Read docs/discovery/research/* (new format)
3. Read .research/* (web researcher output)

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...

Step 3: Create C4 Diagrams (REQUIRED)

Create each diagram in Mermaid format (.mmd files):

For each diagram:

1. Use the template from docs/discovery/diagrams/ as starting point
2. Populate with actual system components
3. Show to user inline using Mermaid code blocks
4. Explain the diagram
5. Get user feedback

Example Context Diagram Creation:

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

Review Questions:

1. Are all users/actors shown?
2. Are all external dependencies captured?
3. Is the trust boundary clear?

**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:

╔═══════════════════════════════════════════════════════════════════════╗ ║ ARCHITECTURE REVIEW GATE ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Please review the architecture before I create the PRD: ║ ║ ║ ║ 📊 Diagrams Created: ║ ║ ✓ Context Diagram - docs/discovery/diagrams/context.mmd ║ ║ ✓ Container Diagram - docs/discovery/diagrams/container.mmd ║ ║ ✓ Data Flow Diagram - docs/discovery/diagrams/dataflow.mmd ║ ║ ✓ Deployment Diagram - docs/discovery/diagrams/deployment.mmd ║ ║ ║ ║ 📄 ADRs Created: [count] ║ ║ ║ ║ 📚 Research Incorporated: ║ ║ - Technology stack from [sources] ║ ║ - Best practices from [sources] ║ ║ - Competitor insights from [sources] ║ ║ ║ ║ To proceed, please say: ║ ║ "Architecture approved" - to continue to PRD synthesis ║ ║ "Change [diagram/decision]" - to modify before proceeding ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════╝

**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:**

DISCOVERY COMPLETE

PRD generated at: docs/PRD.md

Summary:

• Requirements: [count]
• Project Type: [type]
• Layer: [L0-L5]
• Dependencies: [count] upstream, [count] downstream

Next steps:

1. Review the PRD
2. Make any edits directly
3. Say "PRD approved, begin automated development" to proceed

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

MUST HAVE

…(truncated)