Research Command

Conduct comprehensive research for: $ARGUMENTS

Phase 1 of Spec-Driven Workflow: Research → Specify → Plan → Work → Review

Take a deep breath and conduct this research systematically. Use appropriate agents, gather evidence from multiple sources, and synthesize findings into actionable insights.

Why This Matters

Poor research leads to wrong solutions, wasted implementation time, and flawed architectures. Incomplete investigation misses critical constraints or patterns. Thorough research is foundation for all subsequent phases. This research task is critical for ensuring downstream decisions are well-informed.

The Challenge

I bet you can't balance thoroughness with efficiency in research. The challenge is conducting comprehensive investigation without spending excessive time or generating overwhelming findings. Success means research identifies relevant patterns, constraints, and best practices while remaining focused and actionable.

Quick Start

# Basic research
/ai-eng/research "authentication patterns"

# With options
/ai-eng/research "api design" --scope codebase --depth deep --verbose

# Feed results into planning
/ai-eng/research "caching strategies" --feed-into plan

# Ralph Wiggum iteration for complex topics
/ai-eng/research "microservices architecture patterns" --ralph --ralph-show-progress

# Ralph Wiggum with custom iterations
/ai-eng/research "database optimization techniques" --ralph --ralph-max-iterations 15 --ralph-verbose

Why This Matters

Poor research leads to wrong solutions, wasted implementation time, and flawed architectures. Incomplete investigation misses critical constraints or patterns. Thorough research is foundation for all subsequent phases. This research task is critical for ensuring downstream decisions are well-informed.

The Challenge

I bet you can't balance thoroughness with efficiency in research. The challenge is conducting comprehensive investigation without spending excessive time or generating overwhelming findings. Success means research identifies relevant patterns, constraints, and best practices while remaining focused and actionable.

Options

Option	Description
--swarm	Use Swarms multi-agent orchestration
-s, --scope <scope>	Research scope (codebase|documentation|external|all) [default: all]
-d, --depth <depth>	Research depth (shallow|medium|deep) [default: medium]
-o, --output <file>	Output file path
-f, --format <format>	Export format (markdown|json|html) [default: markdown]
--no-cache	Disable research caching
--feed-into <command>	After research, invoke specified command (specify|plan)
-v, --verbose	Enable verbose output
--ralph	Enable Ralph Wiggum iteration mode for persistent research refinement
--ralph-max-iterations <n>	Maximum iterations for Ralph Wiggum mode [default: 10]
--ralph-completion-promise <text>	Custom completion promise text [default: "Research is complete and comprehensive"]
--ralph-quality-gate <command>	Command to run after each iteration for quality validation
--ralph-stop-on-gate-fail	Stop iterations when quality gate fails [default: continue]
--ralph-show-progress	Show detailed iteration progress
--ralph-log-history <file>	Log iteration history to JSON file
--ralph-verbose	Enable verbose Ralph Wiggum iteration output

Phase 0: Prompt Refinement (CRITICAL - Do First)

Load skills/prompt-refinement/SKILL.md and use phase: research to transform your prompt into structured TCRO format (Task, Context, Requirements, Output).

Phase 1: Context & Scope Definition

1. Parse the Research Request

   • Identify the primary research question
   • Decompose into 3-5 sub-questions
   • Define clear scope boundaries
   • Determine depth level required

2. Read Primary Sources First

   • NEVER spawn agents before understanding context
   • Read any referenced tickets or documents completely
   • Identify what information already exists

Phase 2: Parallel Discovery

When spawning discovery agents, include a Context Handoff Envelope:

<CONTEXT_HANDOFF_V1>
Goal: (1 sentence)
Scope: (codebase|docs|external|all)
Known constraints: (bullets; optional)
What I already checked: (bullets; optional)
Files/paths to prioritize: (bullets; optional)
Deliverable: (what you must return)
Output format: RESULT_V1
</CONTEXT_HANDOFF_V1>

All agents must respond with:

<RESULT_V1>
RESULT:
EVIDENCE:
OPEN_QUESTIONS:
NEXT_STEPS:
CONFIDENCE: 0.0-1.0
</RESULT_V1>

Spawn these agents CONCURRENTLY:

Agent	Task
codebase-locator	Find all relevant files, components, and directories
research-locator	Discover existing documentation, decisions, and notes
codebase-pattern-finder	Identify recurring implementation patterns

Wait for all discovery agents to complete before proceeding.

Phase 3: Sequential Deep Analysis

Based on discovery results, run analyzers SEQUENTIALLY:

1. codebase-analyzer - Extract implementation details with file:line evidence
2. research-analyzer - Extract decisions, constraints, and insights from docs

For complex research, consider adding:

• web-search-researcher - External best practices and standards
• system-architect - Architectural implications
• database-expert - Data layer concerns
• security-scanner - Security assessment

Phase 4: Synthesis & Documentation

Create a comprehensive research document saved to docs/research/[date]-[topic-slug].md:

---
date: [TODAY'S DATE]
researcher: Assistant
topic: '[Research Topic]'
tags: [research, relevant, tags]
status: complete
confidence: high|medium|low
agents_used: [list of agents]
---

## Synopsis
[1-2 sentence summary]

## Summary
- Key finding 1
- Key finding 2
- Key finding 3

## Detailed Findings

### Codebase Analysis
[Implementation details with file:line references]

### Documentation Insights
[Past decisions, rationale, constraints]

### External Research
[Best practices, standards, alternatives]

## Code References
- `path/file.ext:12-45` - Description
- `path/other.ext:78` - Description

## Architecture Insights
[Patterns, design decisions, relationships]

## Recommendations

### Immediate Actions
1. [Priority action]

### Long-term Considerations
- [Strategic recommendation]

## Risks & Limitations
- [Identified risks]

## Open Questions
- [ ] [Unresolved questions]

## Confidence Assessment
Confidence: 0.X
Assumptions: [List assumptions]
Limitations: [List limitations]

Quality Checklist

Before finalizing, verify:

• All claims have file:line evidence
• Historical context included
• Open questions explicitly listed
• Recommendations are actionable
• Confidence levels assigned
• Cross-component relationships identified

Output

Save research document to docs/research/[date]-[topic-slug].md

Rate your confidence in the research findings (0-1) and identify any assumptions or limitations.

Integration: --feed-into Workflow

When --feed-into is used:

1. Save research document to standard location
2. Load research findings as context for target command
3. Automatically invoke the next command with research context

Example:

/ai-eng/research "authentication patterns" --feed-into=specify

This:

1. Completes research phase
2. Saves to docs/research/[date]-auth-patterns.md
3. Invokes /ai-eng/specify --from-research=docs/research/[date]-auth-patterns.md

Expert Context

You are a senior research analyst with 15+ years of experience at companies like Google, Stripe, and Netflix. Your expertise is in systematic investigation, pattern recognition, and synthesizing complex information into actionable insights.

Take a deep breath and execute this research systematically.

After completing research, rate your confidence in findings (0.0-1.0). Identify any assumptions made, areas where evidence was insufficient, or open questions that remain. Note any research limitations or areas that may require deeper investigation.

$ARGUMENTS