research

Research Skill

Announce at start: "I'm using the research skill to conduct deep technical research before planning."

Overview

Deep research that surfaces issues before they become bugs. Dispatches 4 parallel agents to analyze codebase (architecture + boundaries + history), external sources (framework docs + best practices), quality (tests + errors + dependencies), and open questions, then synthesizes findings into a persistent research document.

Context isolation: When dispatching research subagents, construct exactly what they need. Subagents should never inherit your session context or history -- you curate their input precisely.

## Requirements (MINIMUM 4 agents, synthesis)

1. Dispatch ALL 4 agents in a single message (MINIMUM - more if open questions exist). Fewer than 4 = VIOLATION. Stop immediately.
2. Synthesize findings into research document. Raw concatenation = invalid output.
3. 4 agents is the floor, not the ceiling.

You have invoked this skill. You MUST: - Follow phases in order (no skipping) - Complete all gates (no self-exemptions) - Produce required outputs (no substitutions)

Failure to comply = skill failure. There is no "partial compliance."

When to Use

Use this skill when:

• Starting work on a new feature area
• Planning requires understanding unfamiliar code
• User explicitly invokes /lighterpowers:research
• Writing-plans skill suggests research first

Do NOT use when:

• Making a quick fix to familiar code
• Research already exists in docs/lighterpowers/research/

The Process

Phase 0: Check for Design Document

If invoked with a path argument:

1. Check if the path points to a file in docs/lighterpowers/designs/ or docs/lighterpowers/plans/
2. If file exists: Read the FULL content (included verbatim in research doc)
3. If file missing: Warn "Design doc not found at [path], falling back to clarification"

If no path provided:

1. Search docs/lighterpowers/designs/ for recent design docs (within 7 days)
2. If found: Ask "Found design doc [filename]. Use this for research?" (Yes/No)
3. If not found or declined: Proceed to Phase 1

When design doc found:

• Store the FULL design document content (included verbatim in Phase 3)
• Extract "Open Questions" section for agent prompts
• Add to each agent prompt: open questions from the design
• Skip Phase 1 clarification

Issue Context Handling in Phase 0

If design doc found with Original Issue block:

• Extract verbatim, store for inclusion in output
• Do NOT re-fetch from issue tracker

If no design doc AND issue ID provided as argument:

1. Dispatch issue-tracking agent:

   Task(description: "Fetch issue body",
        prompt: "Operation: get-issue-body
   Issue: [issue ID from argument]",
        model: "haiku",
        subagent_type: "lighterpowers:issue-tracking:issue-tracking")
   

2. Assess and confirm classification
3. Store for inclusion in output

If neither design doc nor issue ID: Proceed without Original Issue block.

Phase 1: Clarify the Topic (if no design doc)

If the research topic is ambiguous, ask 2-3 targeted questions using AskUserQuestion. If clear, proceed directly to Phase 2.

Phase 2: Dispatch Parallel Research Agents

Dispatch Verification (check BEFORE dispatching)

You will dispatch exactly 4 agents:

1. codebase-analyst (covers: architecture + boundaries + git history)
2. external-researcher (covers: framework docs + best practices)
3. quality-analyst (covers: test coverage + error handling + dependencies)
4. assumption-checker (validates technical assumptions)

Common Rationalizations (ALL INVALID)

Thought	Reality
"I'll dispatch the most relevant agents"	ALL 4 agents are relevant. Each covers a unique domain.
"These agents overlap"	They don't. Each consolidated agent covers distinct data sources.
"To save time/tokens"	4 parallel agents IS the efficient approach.
"Given the simple topic"	No topic is too simple for all 4.
"I already know the answer"	Research validates, doesn't assume. Dispatch all 4.

Dispatch Gate (Required - NEVER skip):

STOP. Before proceeding, verify you will dispatch ALL of these in ONE message:

• codebase-analyst
• external-researcher
• quality-analyst
• assumption-checker

STOP CONDITION (MANDATORY): Count your Task calls before dispatching.

• Less than 4 = VIOLATION. Do not proceed.
• Minimum agents = 4

If count is wrong, FIX IT before proceeding. No exceptions.

Dispatch all 4 agents now:

# Agent 1 of 4: Codebase Analysis (architecture + boundaries + git history)
Task(description: "Analyze codebase patterns, boundaries, and history",
     prompt: [codebase-analyst methodology with topic and open questions],
     model: "haiku",
     subagent_type: "lighterpowers:research:codebase-analyst")

# Agent 2 of 4: External Research (framework docs + best practices)
Task(description: "Research framework docs and best practices",
     prompt: [external-researcher methodology with topic and open questions],
     model: "haiku",
     subagent_type: "lighterpowers:research:external-researcher")

# Agent 3 of 4: Quality Analysis (tests + errors + dependencies)
Task(description: "Analyze test coverage, error handling, and dependencies",
     prompt: [quality-analyst methodology with topic and open questions],
     model: "haiku",
     subagent_type: "lighterpowers:research:quality-analyst")

# Agent 4 of 4: Assumption Validation
Task(description: "Validate technical assumptions",
     prompt: "[design document or topic summary]
     Validate all technical assumptions.
     Return structured output with Validated/Invalid/Unverified sections.",
     model: "haiku",
     subagent_type: "lighterpowers:assumption-checker")

Each agent prompt should include:

• The specific research topic
• Any open questions from the design document
• The output format expected

Phase 2.5a: Open Question Agents (Conditional)

If design document had an "Open Questions" section, dispatch additional agents:

Step 1: Dispatch one additional agent per open question:

Task(
  description: "Investigate: [3-5 word question summary]",
  prompt: "Focus ONLY on this open question from the design doc:
  '[full question text]'

  Research this specific question thoroughly. Provide:
  1. Direct answer if possible
  2. Evidence from codebase/docs/web
  3. Confidence level (high/medium/low)
  4. Remaining unknowns",
  model: "haiku",
  subagent_type: "lighterpowers:research:open-questions-handler"
)

Step 2: Update dispatch count: Total agents = 4 core + N open question agents

Skip Condition: If no "Open Questions" section, skip Phase 2.5a.

Phase 2.6: Issue Discovery (Optional)

If an issue tracker is detected, dispatch issue-tracking agent:

Task(description: "Discover related issues",
     prompt: "Operation: discover
Context: [research topic]
Branch: [current branch name if relevant]",
     model: "haiku",
     subagent_type: "lighterpowers:issue-tracking:issue-tracking")

If no tracker detected, skip (note in output).

Phase 3: Synthesize Findings

After all agents complete, synthesize findings into a research document.

Research Document Format:

# Research: [Topic]

> Generated: [YYYY-MM-DD]
> Design Doc: docs/lighterpowers/designs/YYYY-MM-DD-<topic>-design.md (if exists)
> Issue: [if linked]

## Original Design Document

[Include the FULL design document content here, verbatim.]

---

## Resolved Questions

| Question | Resolution | Source |
|----------|------------|--------|
| [open question from design] | [answer from research] | [agent that answered] |

## Original Issue

> **ID:** [issue-id]
> **Title:** [title]
> **Status:** Authoritative | Reference Only
> **Reason:** [classification reason]

[Full issue body verbatim]

---

## Executive Summary
- [5-7 key findings as bullets]
- Critical constraints discovered
- Recommended approach

## Codebase Analysis
[From codebase-analyst agent -- covers architecture, boundaries, and git history]
- Architecture patterns found
- Similar implementations (with file paths)
- Module boundaries relevant to task
- Code evolution and key decisions
- Conventions to follow

## External Research
[From external-researcher agent -- covers framework docs and best practices]
- API details discovered
- Version-specific considerations
- Current community patterns
- Security considerations
- Performance implications

## Quality Analysis
[From quality-analyst agent -- covers tests, errors, and dependencies]
- Existing test patterns and coverage gaps
- Error patterns and failure modes
- Relevant dependencies and version constraints
- Recovery strategies

## Related Issues

| ID | Title | Status | Source |
|----|-------|--------|--------|
| [id] | [title] | [status] | [source] |

**Note:** [If no tracker: "No issue tracker detected."]

## Validated Assumptions

[From assumption-checker agent]

### Validated
### Invalid
### Unverified

## Edge Cases & Gotchas
[Synthesized from all agents]

## Open Questions
- Things research couldn't resolve
- Decisions needed before planning

Agent Output Consumption Gate

Before saving, verify all agents' findings are incorporated:

• All 4 core agents' findings cited
• All open question agents' findings cited (if Phase 2.5a executed)
• Key findings from EACH agent quoted in synthesis
• Contradictions or tensions between agents noted
• No agent's findings silently dropped

STOP CONDITION: If synthesis doesn't cite all agents, stop. Quote findings from missing agents.

### Synthesis Verification (check BEFORE saving)

• Executive Summary written (your synthesis, not copy-paste)
• All 4 agent sections populated (Codebase, External, Quality, Assumptions)
• Edge Cases synthesized from multiple agents
• Contradictions or within-agent tensions noted

STOP CONDITION: If any section empty or placeholder, complete before saving.

Per-Agent Citation Checklist:

• Codebase Analyst findings cited
• External Researcher findings cited
• Quality Analyst findings cited
• Assumption Checker findings cited

STOP CONDITION: If any agent missing from synthesis, incorporate their findings.

Phase 4: Save Research Document

Save to: docs/lighterpowers/research/YYYY-MM-DD-<topic-slug>.md

Output Gate (Required - NEVER skip):

STOP. Before announcing completion, verify:

• File EXISTS at docs/lighterpowers/research/YYYY-MM-DD-<topic-slug>.md
• Quote the first line of the file you just wrote
• Store this exact path for Phase 5 handoff

If file doesn't exist, write it now.

Path Reminder: Your OUTPUT is docs/lighterpowers/research/..., your INPUT was docs/lighterpowers/designs/....

Phase 5: Announce Completion

Completion Enforcement (CRITICAL):

Your FINAL message MUST contain:

Research complete and saved to `docs/lighterpowers/research/<actual-filename>.md`.

To continue:
/clear
/lighterpowers:write-plan docs/lighterpowers/research/<actual-filename>.md

If NO: Add it. You cannot announce completion without this exact block.

### Handoff Path Verification Gate

• Handoff path starts with docs/lighterpowers/research/ (NOT designs/)
• Handoff path matches the file saved in Phase 4

Wrong Path	Why It's Wrong	Correct Path
docs/lighterpowers/designs/...	This is your INPUT	docs/lighterpowers/research/...

Before announcing completion, verify: - [ ] Completed all phases in order (0 -> 1 -> 2 -> 2.5 -> 3 -> 4 -> 5) - [ ] Passed all verification gates (Dispatch Gate, Synthesis Verification, Output Gate) - [ ] Produced required outputs (research document at docs/lighterpowers/research/)

If ANY unchecked, go back and complete missing steps.

## Requirements (reminder)

1. Dispatch ALL 4 agents in a single message (MINIMUM). Fewer than 4 = VIOLATION.
2. Synthesize findings into research document. Raw concatenation = invalid output.
3. 4 agents is the floor, not the ceiling.

Quick Reference

Phase	Action	Output
0	Check design doc	Full design content or proceed
1	Clarify topic (if no design)	Clear research question
2	Dispatch 4 agents	Parallel research
2.5a	Open question agents	Additional targeted research
2.6	Discover issues	Related issues list
3	Synthesize	Combined findings
4	Save	docs/lighterpowers/research/YYYY-MM-DD-topic.md
5	Announce	Ready for planning

Red Flags - Stop and Recover

Violation	Why It's Critical	Recovery
Dispatching < 4 agents	Violates minimum agent requirement	Stop, add missing agents
Ignoring open questions	Open questions need dedicated agents	Dispatch 1 agent each
Writing doc before agents complete	Missing findings	Wait for all results
Concatenating without synthesizing	Raw output is not research	Write Executive Summary + Edge Cases
Handoff suggests design doc path	Design doc is INPUT, research doc is OUTPUT	Use research doc path