Research

Research

The first phase of development: understand the problem, explore the codebase, design the approach, and decompose into spec-able units.

When to Use This Skill

• Starting work on a new feature or enhancement
• Investigating a bug or issue
• Planning a refactor or migration
• Decomposing a large change into smaller pieces
• Any time you need to understand before you build

Workflow Overview

Understand Request
       │
       ▼
Explore Codebase ──────► Dialog with User
       │                      │
       ▼                      ▼
Architectural Design ◄───► Scope Decisions
       │
       ▼
Interface Contracts ───► Test Planning (from contracts)
       │
       ▼
Decompose into Specs
       │
       ▼
Create FEATURE.md
       │
       ▼
Create ALL spec-research.md files
       │
       ▼
QC Validation (research-qc agent)
       │
       ├─ FAIL → Address issues, re-run QC
       │
       ▼
Commit to main
       │
       ▼
Create Spec Tasks
       │
       ▼
Output: Research complete, ready for spec

---

Step 1: Understand the Request

1. Clarify the goal: What problem are we solving? What's the desired outcome? 2. Identify constraints: Timeline, dependencies, existing patterns to follow 3. Check existing work: Is there a FEATURE.md? Previous specs? Related features?

Ask if unclear:

Use AskUserQuestion if the request is ambiguous:
- "What's the primary goal here?"
- "Are there constraints I should know about?"

---

Step 2: Explore the Codebase

Use the built-in Explore agent (via Task tool) for thorough investigation.

Launch exploration:

subagent_type: "Explore"
description: "Explore [area] for [purpose]"
prompt: "I need to understand [specific question].
Look for: [patterns, files, implementations].
Report: key files, existing patterns, integration points."

What to explore:

• Similar features or implementations
• Existing patterns and conventions
• Integration points and dependencies
• Test patterns and coverage

Thoroughness levels:

• quick - Basic file search, known locations
• medium - Moderate exploration, multiple areas
• very thorough - Comprehensive analysis

API Exploration Prompt

When exploring backend endpoints, document the full response schema:

Find the backend endpoints for {feature} data.

For each endpoint discovered:
1. Document the URL, method, and parameters
2. List ALL fields in the response schema (read actual code/types)
3. Note any computed or derived fields
4. Flag if response doesn't include fields the UI/feature seems to need

Output format:

## Endpoint: {path}
**Method:** GET/POST
**Parameters:** {list}

**Response Schema:**
| Field | Type | Notes |
|-------|------|-------|

**Potential Gaps:** {fields the UI/feature needs but aren't in the response}

Pattern Exploration Prompt

When finding reference patterns to follow, trace the complete data flow:

Find how {similar feature} implements {capability}.

Document:
1. Key files and their responsibilities
2. Data flow: where does data come from?
3. Props/interfaces: what does each component expect?
4. For each data input, trace to its source (API call, computed, parent prop)

Output format:

## Pattern: {name}
**Key Files:** {list}

**Data Flow:**
{component}
  ← receives: {props}
  ← from: {parent}
  ← which gets it from: {API/hook/context}

---

Step 3: Dialog with User (Interactive Feedback)

Use AskUserQuestion at key decision points. Present findings first, then ask.

Decision Point 1: Scope Confirmation

After initial exploration, confirm scope:

"Based on exploration, this involves:
- [Component A] - [what needs to change]
- [Component B] - [what needs to change]
- [Component C] - [what needs to change]

Should we include all of these, or narrow the scope?"

Options:
- Include all (comprehensive)
- Focus on [subset] first
- Other

Decision Point 2: Architectural Approach

When multiple patterns or approaches exist:

"Found two approaches in the codebase:

1. **[Pattern A]** - Used in [X, Y]
   - Pros: [...]
   - Cons: [...]

2. **[Pattern B]** - Used in [Z]
   - Pros: [...]
   - Cons: [...]

Which approach fits better for this change?"

Decision Point 3: Test Strategy

For testing approach:

"Existing tests use [pattern/framework].

Options:
- Follow existing pattern
- Use [alternative] because [reason]
- Mix: [specific suggestion]"

Guidelines for AskUserQuestion:

• Present findings first - Show your work before asking
• Concrete options - 2-4 specific choices, not open-ended
• Don't over-ask - Save for real decision points
• Include context - Why does this decision matter?

---

Step 4: Architectural Design

Document the chosen approach:

1. High-level design: How components interact 2. Key decisions: What was decided and why 3. Files affected: What will be created/modified 4. Integration points: How this connects to existing code

---

Step 5: Interface Contracts

Define the interfaces before implementation:

1. Types: Key data structures and interfaces 2. Function signatures: Input/output contracts 3. API changes: New or modified endpoints 4. Dependencies: What depends on what

This enables clear boundaries for decomposition AND test planning.

Source Tracing Requirement

For each field in each interface, document its source:

• API endpoint + field name
• Computed from X
• Passed as prop from Y
• If source unknown: mark ⚠️ TBD

TBD items must be resolved before decomposition:

• Identify real source, OR
• Add to backend work scope, OR
• Descope the field

Example formats:

Inline annotation:

interface SupportMetrics {
  total_tickets: number;      // ← API: /get-metrics.total_tickets
  solved_count: number;       // ← ⚠️ TBD - needs resolution
}

Or companion table:

### SupportMetrics Sources
| Field | Source |
|-------|--------|
| total_tickets | /get-metrics.total_tickets |
| solved_count | ⚠️ TBD |

---

Step 6: Test Planning (from Interface Contracts)

After Interface Contracts are defined, derive test cases from them.

For each function contract, identify:

Output format:

## Test Plan

### {function_name}
**Signature:** `{signature}`

**Happy Path:**
- [ ] {test case description}

**Edge Cases:**
- [ ] Empty input: {expected behavior}
- [ ] Null handling: {expected behavior}
- [ ] Boundary: {expected behavior}

**Error Cases:**
- [ ] Network failure: {expected behavior}
- [ ] Invalid input: {expected behavior}

**Mocks Needed:**
- {dependency}: {mock strategy}

This test plan feeds directly into Phase X.0 of implement.

---

Step 7: Decompose into Specs

Break work into implementable units:

Decomposition Principles:

• Single responsibility: Each spec does one thing
• Clear boundaries: Minimal overlap between specs
• Testable in isolation: Can verify without other specs
• PR reviewable: Each spec produces a mergeable PR (3-5 FRs, ~200-400 lines of spec → ~300-600 lines of code)
• Complete in isolation: Each spec adds value even if other specs are delayed

Ask User for Decomposition Preference:

"This work can be decomposed as:

Option A: By layer
1. Data layer changes
2. Business logic
3. UI updates

Option B: By feature slice
1. Core functionality
2. Edge cases
3. Polish/optimization

Option C: By dependency order
1. [Foundation piece]
2. [Depends on 1]
3. [Depends on 2]

Which decomposition makes more sense?"

Document Each Spec Unit:

For each decomposed piece, create a dependency-aware table:

Column definitions:

• Spec: Numbered identifier (NN-name format)
• Description: Brief summary of what the spec covers
• Blocks: Which specs depend on this one (enables parallel execution planning)
• Blocked By: Which specs must complete before this one can start
• Complexity: S (small), M (medium), L (large)

This table enables Task-based parallel execution after research completes.

Coverage Verification

Before finalizing decomposition, verify coverage:

For each data source identified in interface contracts:

• If existing code → note "existing" (no spec needed)
• If new code needed → assign to a specific spec
• If neither → flag as orphaned dependency

For each "Deferred to X" in Out of Scope:

• Verify X exists in the decomposition

Checklist before finalizing:

• [ ] Every "needs new code" source has a spec assigned
• [ ] Every deferred item points to a real spec
• [ ] No spec depends on something that isn't existing or spec'd
• [ ] No ⚠️ TBD items remain in interface contracts (resolve or escalate)
• [ ] No ⚠️ Unassigned items remain in Out of Scope
• [ ] Each spec has 3-5 FRs (max 8) for reasonable PR size
• [ ] Each spec is independently mergeable (no dangling dependencies)
• [ ] Dependency graph has no cycles (validate Blocks/Blocked By columns)

---

Step 8: Create FEATURE.md

If new feature: 1. Create features/{domain}/{feature}/FEATURE.md 2. Use FEATURE-TEMPLATE.md 3. Fill in based on research findings

If existing feature: 1. Update sections based on new understanding 2. Keep as "intended final state" (not incremental changes)

---

Step 9: Create ALL Spec Structures

Create folders and spec-research.md for ALL decomposed specs:

# Create all spec folders
mkdir -p features/{domain}/{feature}/specs/01-{spec-name}
mkdir -p features/{domain}/{feature}/specs/02-{spec-name}
mkdir -p features/{domain}/{feature}/specs/03-{spec-name}
# ... for each decomposed spec

Output `spec-research.md` in EACH spec folder:

Use spec-research-template.md.

Each document captures (for THAT spec):

• Problem context
• Exploration findings
• Key decisions (with rationale)
• Interface contracts
• Test plan (derived from contracts)
• Files to reference

---

Step 10: QC Validation

Before committing, spawn the research-qc agent to validate outputs.

Launch QC Agent

subagent_type: "research-qc"
description: "Validate research outputs"
prompt: "Validate the research outputs for feature at:
- FEATURE.md: features/{domain}/{feature}/FEATURE.md
- Specs directory: features/{domain}/{feature}/specs/

Read FEATURE.md and all spec-research.md files. Run all checks and report PASS or FAIL."

Handle QC Results

If PASS:

• Proceed to commit (Step 11)

If FAIL: 1. Review the specific issues listed 2. Address each issue in the relevant files 3. Re-run the research-qc agent 4. Repeat until PASS (max 2-3 iterations)

If stuck after 2-3 iterations:

• Escalate to user with remaining issues
• User decides: fix manually, proceed with known gaps, or change approach

---

Step 11: Commit Research Artifacts

Stage specific files and commit:

git add features/{domain}/{feature}/FEATURE.md
git add features/{domain}/{feature}/specs/*/spec-research.md
git commit -m "$(cat <<'EOF'
research({feature}): add FEATURE.md and spec-research for {N} specs

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Important: Stage specific files, not git add -A.

---

Step 12: Create Tasks and Handoff

Create Spec Tasks

After research is committed, create Tasks for parallel spec execution:

For each spec in the decomposition table: 1. Use TaskCreate with subject "Spec + Implement {NN}-{name}" 2. Include spec path and description 3. Map Blocked By column to blockedBy parameter

Example:

TaskCreate:
  subject: "Spec + Implement 01-foundation"
  description: "Run spec and implement skills for features/{domain}/{feature}/specs/01-foundation"

TaskCreate:
  subject: "Spec + Implement 02-data-layer"
  description: "Run spec and implement skills for features/{domain}/{feature}/specs/02-data-layer"
  blockedBy: [task-id-of-01]

TaskCreate:
  subject: "Spec + Implement 03-ui"
  description: "Run spec and implement skills for features/{domain}/{feature}/specs/03-ui"
  blockedBy: [task-id-of-01, task-id-of-02]

Report to user:

• Task IDs created
• Dependency graph visualization
• Which tasks are immediately actionable (no blockers)
• Handoff instruction: Run /orchestrate in a fresh session

Example output:

"Created {N} spec tasks with dependencies:

Task IDs:
- #1: Spec + Implement 01-foundation (no blockers - ready)
- #2: Spec + Implement 02-data-layer (blocked by: #1)
- #3: Spec + Implement 03-ui (blocked by: #1, #2)

Dependency Graph:
01-foundation
    ├── 02-data-layer
    │       └── 03-ui
    └── 03-ui

Ready to execute: 01-foundation

NEXT STEP:
Start a fresh session and run:
  /orchestrate features/{domain}/{feature}

This will spawn spec-executor agents for all unblocked specs."

---

Key Principles

• Explore before deciding - Don't assume, investigate
• Dialog at decision points - Use AskUserQuestion for real choices
• Document decisions - Capture rationale, not just conclusions
• Test plan from contracts - Derive tests from interface definitions
• Decompose thoughtfully - Right-sized specs enable parallel work
• Track dependencies - Blocks/Blocked By enables parallel execution
• FEATURE.md is the north star - It shows intended final state
• spec-research.md is per-spec - Each spec gets focused context
• Clean handoff - Committed artifacts before creating Tasks

Feature: {Feature Name}

Feature ID

{feature-id}

Metadata

Files Touched

{Category}

• {path/to/file} ({action: new/modify})

Table of Contents

• Feature Overview
• Intended State
• System Architecture
• Changelog of Feature Specs

Feature Overview

Summary

{1-2 sentences describing what this feature does.}

Problem Statement

{What problem does this feature solve? Why is it needed?}

Goals

• {Goal 1}
• {Goal 2}

Non-Goals

• {What is explicitly NOT included} - {why}

Intended State

{Description of the feature when complete. Write as if describing the finished product, not the changes needed.}

Key Behaviors

1. {Behavior}: {Description} 2. {Behavior}: {Description}

System Architecture

Component Structure

{Diagram or structure showing how components relate}

Data Flow

{How data moves through the system}

Changelog of Feature Specs

Spec Research: {Spec Name}

Date: {YYYY-MM-DD} Author: @{github-id} Spec: {NN}-{spec-name}

---

Problem Context

{What problem does this spec address? What's the scope?}

---

Exploration Findings

Existing Patterns

{What patterns exist in the codebase for similar functionality?}

Key Files

Integration Points

{How does this connect to existing systems?}

• {Integration point 1}
• {Integration point 2}

---

Key Decisions

Decision 1: {Topic}

Options considered: 1. {Option A} - {pros/cons} 2. {Option B} - {pros/cons}

Chosen: {Option X}

Rationale: {Why this was selected}

---

Interface Contracts

Types

// Key interfaces for this spec
interface {Name} {
  {fields}
}

Function Contracts

---

Test Plan

Derived from Interface Contracts above. This defines WHAT to test. The checklist.md tracks execution.

{function_name}

Signature: {signature}

Happy Path:

• {test case}: {expected behavior}
• {test case}: {expected behavior}

Edge Cases:

• Empty input: {expected behavior}
• Null/undefined: {expected behavior}
• Boundary values: {expected behavior}

Error Cases:

• Network failure: {expected behavior}
• Invalid input: {expected behavior}
• State conflict: {expected behavior}

Mocks Needed:

• {dependency}: {mock strategy}

{next_function_name}

{Same format...}

---

Files to Create/Modify

---

Edge Cases to Handle

1. {Case} - {How to handle} 2. {Case} - {How to handle}

---

Open Questions

Must be empty before research phase completes. Use this section to track questions during exploration, then resolve each before finalizing.

<!-- Example of resolved question: ✓ How should we handle rate limiting? → Decided: Use exponential backoff, documented in Key Decisions. -->

None remaining.