discover

Purpose

Transform a user's feature idea into a detailed specification through a unified discovery flow. This skill combines brief creation and discovery into a single streamlined process with adaptive depth based on complexity assessment.

When to Use

• User says "I want to build...", "Add a feature for...", "We need..."
• User describes a new capability or enhancement
• Starting a new project or significant feature
• User explicitly invokes /discover

---

Complexity Levels

| Level | Questions | SME Agents | Typical Use Case | |-------|-----------|------------|------------------| | quick | 3 essential | None (skip to spec) | Small enhancements, bug fixes, config changes | | standard | 5-6 questions | Technical + Business | Most features, new functionality | | complex | 8+ questions | Full SME review + custom agents | Large initiatives, architectural changes, cross-cutting concerns |

---

Process

Step 0: Path Detection

Determine the location of discovery.db to support both new .parade/ structure and legacy project root:

# Path detection for .parade/ structure
if [ -f ".parade/discovery.db" ]; then
  DISCOVERY_DB=".parade/discovery.db"
else
  DISCOVERY_DB="./discovery.db"
fi

All subsequent database operations in this skill use $DISCOVERY_DB instead of hardcoded discovery.db.

Step 1: Capture Initial Idea

Ask the user to describe their feature idea. Listen for:

• What they want to build
• Why they need it (problem being solved)
• Who it's for (user persona)

Step 2: Complexity Assessment

After hearing the initial idea, ask:

Before we dive in, let me understand the scope:

Is this a:
1. **Quick enhancement** - Small change, clear scope, minimal risk
2. **Standard feature** - New functionality requiring design and implementation
3. **Complex initiative** - Large scope, architectural impact, cross-team concerns

(Enter 1, 2, or 3, or describe and I'll assess)

Map response to complexity level:

• 1 or "quick/small/simple/minor" -> quick
• 2 or "standard/normal/feature/medium" -> standard
• 3 or "complex/large/initiative/major/architecture" -> complex

Step 3: Generate Brief ID

Create a kebab-case ID from the title:

"Add athlete experience tracking" -> "athlete-experience-tracking"

Step 4: Initialize Database and Create Brief

Run schema migration and insert brief:

# Ensure tables exist with complexity_level column
sqlite3 "$DISCOVERY_DB" "
CREATE TABLE IF NOT EXISTS briefs (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  problem_statement TEXT,
  initial_thoughts TEXT,
  priority INTEGER DEFAULT 2,
  complexity_level TEXT DEFAULT 'standard',
  status TEXT DEFAULT 'draft',
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT,
  exported_epic_id TEXT
);

-- Migration: Add complexity_level if missing (idempotent)
ALTER TABLE briefs ADD COLUMN complexity_level TEXT DEFAULT 'standard';
"

# Insert the brief
sqlite3 "$DISCOVERY_DB" "INSERT INTO briefs (id, title, problem_statement, initial_thoughts, priority, complexity_level, status)
VALUES ('<brief-id>', '<title>', '<problem>', '<initial_thoughts>', <priority>, '<complexity_level>', 'in_discovery');"

Step 5: Generate and Present Batched Questions

Generate questions based on complexity level, then present ALL at once:

Quick (3 questions)

## Discovery: <brief-title>
Complexity: Quick Enhancement

Please answer these 3 questions:

1. [scope] What exactly needs to change? (files, components, behavior)
2. [success] How will we verify this works correctly?
3. [risk] Any edge cases or risks to consider?

Standard (5-6 questions)

## Discovery: <brief-title>
Complexity: Standard Feature

Please answer these questions (all at once is fine):

**Technical**
1. How should this integrate with existing data models and components?
2. Are there performance or scalability considerations?

**Business**
3. Who are the primary users and what's their workflow?
4. What metrics will indicate success?

**UX/Scope**
5. Walk me through the ideal user flow.
6. What's in MVP vs future phases?

Complex (8+ questions)

## Discovery: <brief-title>
Complexity: Complex Initiative

Please answer these questions (take your time, all at once is fine):

**Technical**
1. How does this fit into the current architecture?
2. What data models, APIs, or services need changes?
3. Are there performance, security, or compliance considerations?

**Business**
4. Who are all the stakeholders affected?
5. What business metrics define success?
6. What's the rollout strategy?

**UX/Scope**
7. Describe the complete user journey.
8. What are the failure modes and error handling needs?
9. What's MVP vs Phase 2 vs future?

**Dependencies**
10. What existing features or systems does this touch?

Step 6: Record Answers

Store questions and answers in the database:

-- Ensure table exists
CREATE TABLE IF NOT EXISTS interview_questions (
  id TEXT PRIMARY KEY,
  brief_id TEXT REFERENCES briefs(id),
  question TEXT NOT NULL,
  category TEXT,
  answer TEXT,
  answered_at TEXT,
  created_at TEXT DEFAULT (datetime('now'))
);

-- Insert all questions with answers
INSERT INTO interview_questions (id, brief_id, question, category, answer, answered_at, created_at)
VALUES
  ('<brief-id>-q1', '<brief-id>', 'Question 1...', 'technical', '<answer1>', datetime('now'), datetime('now')),
  ('<brief-id>-q2', '<brief-id>', 'Question 2...', 'business', '<answer2>', datetime('now'), datetime('now')),
  ...;

Step 7: SME Review (Based on Complexity)

Quick -> Skip SME, proceed directly to Step 8

For quick enhancements, skip SME agents entirely and proceed to spec synthesis.

Standard -> Spawn Technical + Business SME

Technical SME Agent:

Task: Technical review for brief '<brief-id>'

Context:
- Read brief: sqlite3 -json "$DISCOVERY_DB" "SELECT * FROM briefs WHERE id = '<brief-id>';"
- Read answers: sqlite3 -json "$DISCOVERY_DB" "SELECT * FROM interview_questions WHERE brief_id = '<brief-id>';"

Analyze:
1. Review existing codebase for relevant patterns
2. Identify technical risks and constraints
3. Suggest architecture approach
4. Flag any concerns

Output: Write findings to sme_reviews table with agent_type = 'technical-sme'

Business SME Agent:

Task: Business review for brief '<brief-id>'

Context:
- Read brief and interview answers from $DISCOVERY_DB

Analyze:
1. Validate requirements completeness
2. Check for missing stakeholder considerations
3. Identify business risks
4. Confirm success metrics are measurable

Output: Write findings to sme_reviews table with agent_type = 'business-sme'

Complex -> Full SME Review + Custom Agents

Spawn Technical SME and Business SME as above, plus:

Check for custom agents in project.yaml:

if [ -f "project.yaml" ]; then
  # Parse agents.custom[] array
  # For each custom agent, spawn with their prompt_file
fi

For each custom agent in project.yaml:

Task: Domain review for brief '<brief-id>'

Context:
- Read brief and interview answers from $DISCOVERY_DB
- Your domain prompt is loaded from <prompt_file>

Output: Write findings to sme_reviews table with agent_type = '<agent-label>'

Insert SME reviews:

CREATE TABLE IF NOT EXISTS sme_reviews (
  id TEXT PRIMARY KEY,
  brief_id TEXT REFERENCES briefs(id),
  agent_type TEXT NOT NULL,
  findings TEXT,
  recommendations TEXT,
  concerns TEXT,
  created_at TEXT DEFAULT (datetime('now'))
);

INSERT INTO sme_reviews (id, brief_id, agent_type, findings, recommendations, concerns, created_at)
VALUES ('<brief-id>-tech-review', '<brief-id>', 'technical-sme', '<findings>', '<recommendations>', '<concerns>', datetime('now'));

Step 7a: Load Design Registries (Pattern Reuse)

Before synthesizing the spec, load existing patterns to ensure consistency:

# Load existing components, fields, and patterns
COMPONENTS_FILE=".design/Components.md"
FIELDS_FILE=".design/Fields.md"
PATTERNS_FILE=".design/Patterns.md"

# Extract key sections for context
if [ -f "$COMPONENTS_FILE" ]; then
  # Get list of documented components
  AVAILABLE_COMPONENTS=$(grep -E "^### " "$COMPONENTS_FILE" | sed 's/### //' | head -20)
fi

if [ -f "$FIELDS_FILE" ]; then
  # Get list of documented fields/enums
  AVAILABLE_FIELDS=$(grep -E "^\| \`" "$FIELDS_FILE" | sed 's/| `//' | cut -d'`' -f1 | head -30)
fi

if [ -f "$PATTERNS_FILE" ]; then
  # Get list of documented patterns
  AVAILABLE_PATTERNS=$(grep -E "^### " "$PATTERNS_FILE" | sed 's/### //' | head -20)
fi

Present available patterns during spec synthesis:

When generating the spec's design notes and task breakdown, reference existing patterns:

Available Components (from .design/Components.md):
- Button, Card, Badge, Input, Select, Dialog, Tabs, Toast, ...

Available Fields (from .design/Fields.md):
- id, created_at, updated_at, status, priority, title, description, ...
- Enums: IssueStatus, IssueType, BriefStatus, Priority, ...

Available Patterns (from .design/Patterns.md):
- Zustand Store Pattern, IPC Handler Pattern, useEffect Data Loading, ...

Spec should reference existing patterns where applicable:

• Use existing components rather than creating new ones
• Reuse field naming conventions and existing enums
• Follow documented patterns for state management, data fetching, etc.

Only propose NEW components/fields/patterns when existing ones don't fit the requirement.

Step 8: Synthesize Spec

Create specification from discovery findings:

CREATE TABLE IF NOT EXISTS specs (
  id TEXT PRIMARY KEY,
  brief_id TEXT REFERENCES briefs(id),
  title TEXT NOT NULL,
  description TEXT,
  acceptance_criteria TEXT,
  design_notes TEXT,
  task_breakdown TEXT,
  status TEXT DEFAULT 'draft',
  approved_at TEXT,
  exported_epic_id TEXT,
  created_at TEXT DEFAULT (datetime('now'))
);

INSERT INTO specs (id, brief_id, title, description, acceptance_criteria, design_notes, task_breakdown, status, created_at)
VALUES (
  '<brief-id>-spec',
  '<brief-id>',
  '<spec title>',
  '<detailed description>',
  '<JSON array of acceptance criteria>',
  '<technical design notes from SME or user answers>',
  '<JSON array of proposed tasks>',
  'review',
  datetime('now')
);

Update brief status:

UPDATE briefs SET status = 'spec_ready', updated_at = datetime('now') WHERE id = '<brief-id>';

Step 9: Present Spec for Review

## Specification Ready for Review

### <Spec Title>
**Complexity:** <quick|standard|complex>

**Description:**
<description>

**Acceptance Criteria:**
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

**Design Notes:**
<technical approach from SME review or derived from answers>

**Patterns & Components:**
*Existing (from registries):*
- Components: Card, Badge, Button (from .design/Components.md)
- Fields: status, priority, created_at (from .design/Fields.md)
- Patterns: Zustand Store, IPC Handler (from .design/Patterns.md)

*New (will be added by /evolve):*
- Component: <NewComponentName> - <brief description>
- Field: <new_field_name> - <type and purpose>
- Pattern: <NewPattern> - <what it does>

**Proposed Tasks:**
1. Task 1: <description> [agent:sql]
2. Task 2: <description> [agent:typescript]
3. Task 3: <description> [agent:swift]

**Dependencies:**
- Task 3 depends on Task 1, Task 2

---

To approve and create beads tasks: /approve-spec <brief-id>-spec
To request changes: Tell me what to revise

Note: New components, fields, and patterns will be captured by /evolve at epic completion and added to the registries for future reuse.

---

Schema Migration

When running /discover, ensure the database schema includes the complexity_level column:

-- Create briefs table if not exists (includes complexity_level)
CREATE TABLE IF NOT EXISTS briefs (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  problem_statement TEXT,
  initial_thoughts TEXT,
  priority INTEGER DEFAULT 2,
  complexity_level TEXT DEFAULT 'standard',
  status TEXT DEFAULT 'draft',
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT,
  exported_epic_id TEXT
);

-- Migration for existing databases (idempotent - SQLite will error if column exists, which is safe)
-- Wrap in try/catch or ignore error:
ALTER TABLE briefs ADD COLUMN complexity_level TEXT DEFAULT 'standard';

For idempotent migration in bash:

sqlite3 "$DISCOVERY_DB" "ALTER TABLE briefs ADD COLUMN complexity_level TEXT DEFAULT 'standard';" 2>/dev/null || true

---

Workflow Events

Log key events throughout the process:

CREATE TABLE IF NOT EXISTS workflow_events (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  brief_id TEXT,
  event_type TEXT,
  details TEXT,
  created_at TEXT DEFAULT (datetime('now'))
);

INSERT INTO workflow_events (brief_id, event_type, details) VALUES
  ('<brief-id>', 'discover_started', '{"complexity": "<level>"}'),
  ('<brief-id>', 'questions_presented', '{"count": <n>, "complexity": "<level>"}'),
  ('<brief-id>', 'answers_recorded', '{}'),
  ('<brief-id>', 'sme_review_started', '{"agents": ["technical-sme", "business-sme"]}'),  -- if applicable
  ('<brief-id>', 'sme_review_complete', '{}'),  -- if applicable
  ('<brief-id>', 'spec_generated', '{"spec_id": "<brief-id>-spec"}');

---

Example Interactions

Quick Enhancement Example

User: I want to change the default sort order in the task list from ascending to descending

Claude: Got it - changing default sort order. This sounds like a quick enhancement.

Is this a:

1. Quick enhancement
2. Standard feature
3. Complex initiative

User: 1

Claude:

## Discovery: default-sort-order-change
Complexity: Quick Enhancement

Please answer these 3 questions:

1. [scope] What exactly needs to change? (files, components, behavior)
2. [success] How will we verify this works correctly?
3. [risk] Any edge cases or risks to consider?

User:

1. Just the TaskList.tsx component, change the default sortDirection from 'asc' to 'desc'
2. Open the task list and confirm newest tasks appear first
3. None really, it's a simple default change

Claude: [Generates spec directly, no SME agents]

Standard Feature Example

User: We need to add a way for users to filter tasks by label

Claude: A label filter - useful feature! Let me assess complexity.

Is this a:

1. Quick enhancement
2. Standard feature
3. Complex initiative

User: Standard feature

Claude:

## Discovery: task-label-filter
Complexity: Standard Feature

Please answer these questions (all at once is fine):

**Technical**
1. How should this integrate with existing data models and components?
2. Are there performance or scalability considerations?

**Business**
3. Who are the primary users and what's their workflow?
4. What metrics will indicate success?

**UX/Scope**
5. Walk me through the ideal user flow.
6. What's in MVP vs future phases?

User: [Provides all answers]

Claude: [Spawns Technical + Business SME, then generates spec]

---

Output

After successful execution:

• Brief record in $DISCOVERY_DB (.parade/discovery.db or ./discovery.db) with complexity_level set
• Interview questions and answers recorded
• SME reviews in sme_reviews table (for standard/complex)
• Spec in specs table with status 'review'
• Brief status updated to 'spec_ready'
• User presented with spec for approval

---

Comparison with Legacy Skills

| Aspect | Legacy (/create-brief + /start-discovery) | New (/discover) | |--------|-------------------------------------------|-----------------| | Commands | 2 separate invocations | 1 unified command | | Questions | Sequential, one at a time | Batched, all at once | | Complexity | Not assessed | Quick/Standard/Complex | | SME agents | Always spawned | Adaptive (skip for quick) | | User effort | More back-and-forth | Streamlined |