v1truv1us Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.
Comprehensive Research Skill
Systematic Approach
Methodology
A systematic multi-phase research orchestration skill that coordinates specialized agents to conduct thorough investigations across codebases, documentation, and external sources. Based on proven patterns from codeflow research workflows with incentive-based prompting enhancements.
How It Works
This skill orchestrates a disciplined research workflow through three primary phases:
- Discovery Phase (Parallel): Multiple locator agents scan simultaneously
- Analysis Phase (Sequential): Deep analyzers process findings with evidence chains
- Synthesis Phase: Consolidated insights with actionable recommendations
Research Methodology
Phase 1: Context & Scope Definition
Before spawning agents, establish:
## Research Scope Analysis
- **Primary Question**: [Core research objective]
- **Decomposed Sub-Questions**: [Derived investigation areas]
- **Scope Boundaries**: [What's in/out of scope]
- **Depth Level**: shallow | medium | deep
- **Expected Deliverables**: [Documentation, recommendations, code refs]
Critical Rule: Always read primary sources fully BEFORE spawning agents.
Phase 2: Parallel Discovery
Spawn these agents concurrently for comprehensive coverage:
| Agent | Purpose | Timeout |
|---|---|---|
codebase-locator |
Find relevant files, components, directories | 5 min |
research-locator |
Discover existing docs, decisions, notes | 3 min |
codebase-pattern-finder |
Identify recurring implementation patterns | 4 min |
Discovery Output Structure:
{
"codebase_files": ["path/file.ext:lines"],
"documentation": ["docs/path.md"],
"patterns_identified": ["pattern-name"],
"coverage_map": {"area": "percentage"}
}
Phase 3: Sequential Deep Analysis
After discovery completes, run analyzers sequentially:
| Agent | Purpose | Depends On |
|---|---|---|
codebase-analyzer |
Implementation details with file:line evidence | codebase-locator |
research-analyzer |
Extract decisions, constraints, insights | research-locator |
For Complex Research, Add:
| Agent | Condition |
|---|---|
web-search-researcher |
External context needed |
system-architect |
Architectural implications |
database-expert |
Data layer concerns |
security-scanner |
Security assessment needed |
Phase 4: Synthesis & Documentation
Aggregate all findings into structured output:
---
date: YYYY-MM-DD
researcher: Assistant
topic: 'Research Topic'
tags: [research, relevant, tags]
status: complete
confidence: high|medium|low
---
## Synopsis
[1-2 sentence summary of research objective and outcome]
## Summary
[3-5 bullet points of high-level findings]
## Detailed Findings
### Component Analysis
- **Finding**: [Description]
- **Evidence**: `file.ext:line-range`
- **Implications**: [What this means]
### Documentation Insights
- **Decisions Made**: [Past architectural decisions]
- **Rationale**: [Why decisions were made]
- **Constraints**: [Technical/operational limits]
### Code References
- `path/file.ext:12-45` - Description of relevance
- `path/other.ext:78` - Key function location
## Architecture Insights
[Key patterns, design decisions, cross-component relationships]
## Historical Context
[Insights from existing documentation, evolution of the system]
## Recommendations
### Immediate Actions
1. [First priority action]
2. [Second priority action]
### Long-term Considerations
- [Strategic recommendation]
## Risks & Limitations
- [Identified risk with mitigation]
- [Research limitation]
## Open Questions
- [ ] [Unresolved question requiring further investigation]
Agent Coordination Best Practices
Execution Order Optimization
┌─────────────────────────────────────────────────────────────┐
│ Phase 1: Discovery (PARALLEL) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │codebase- │ │research- │ │codebase-pattern- │ │
│ │locator │ │locator │ │finder │ │
│ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │
│ │ │ │ │
│ └────────────────┼─────────────────────┘ │
│ ▼ │
├─────────────────────────────────────────────────────────────┤
│ Phase 2: Analysis (SEQUENTIAL) │
│ ┌──────────────┐ ┌──────────────┐ │
│ │codebase- │──────▶│research- │ │
│ │analyzer │ │analyzer │ │
│ └──────────────┘ └──────────────┘ │
│ │
├─────────────────────────────────────────────────────────────┤
│ Phase 3: Domain Specialists (CONDITIONAL) │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │web-search- │ │database- │ │security- │ │
│ │researcher │ │expert │ │scanner │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │
├─────────────────────────────────────────────────────────────┤
│ Phase 4: Validation (PARALLEL) │
│ ┌──────────────┐ ┌──────────────┐ │
│ │code-reviewer │ │architect- │ │
│ │ │ │review │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
Quality Indicators
- Comprehensive Coverage: Multiple agents provide overlapping validation
- Evidence-Based: All findings include specific file:line references
- Contextual Depth: Historical decisions and rationale included
- Actionable Insights: Clear next steps provided
- Risk Assessment: Potential issues identified
Caching Strategy
Cache Configuration
type: hierarchical
ttl: 3600 # 1 hour
invalidation: manual
scope: command
What to Cache
- Successful agent coordination strategies for similar topics
- Effective agent combinations
- Question decomposition patterns
- Pattern recognition results
Cache Performance Targets
- Hit rate: ≥60%
- Memory usage: <30MB
- Response time improvement: <150ms
Error Handling
Common Failure Modes
| Scenario | Phase | Mitigation |
|---|---|---|
| Invalid research question | Context Analysis | Request clarification |
| Agent timeout | Discovery/Analysis | Retry with reduced scope |
| Insufficient findings | Synthesis | Expand scope, add agents |
| Conflicting information | Synthesis | Document conflicts, flag for review |
Escalation Triggers
- Multiple agent failures
- Scope exceeds single-session capacity
- Cross-repository research needed
- External API/service investigation required
Structured Output Format
{
"status": "success|in_progress|error",
"timestamp": "ISO-8601",
"cache": {
"hit": true,
"key": "pattern:{hash}:{scope}",
"ttl_remaining": 3600,
"savings": 0.25
},
"research": {
"question": "Primary research question",
"scope": "codebase|documentation|external|all",
"depth": "shallow|medium|deep"
},
"findings": {
"total_files": 23,
"codebase_refs": 18,
"documentation_refs": 5,
"insights_generated": 7,
"patterns_identified": 3
},
"document": {
"path": "docs/research/YYYY-MM-DD-topic.md",
"sections": ["synopsis", "summary", "findings", "recommendations"],
"code_references": 12,
"historical_context": 3
},
"agents_used": [
"codebase-locator",
"research-locator",
"codebase-analyzer",
"research-analyzer"
],
"metadata": {
"processing_time_seconds": 180,
"cache_savings_percent": 0.25,
"agent_tasks_completed": 6,
"follow_up_items": 2
},
"confidence": {
"overall": 0.85,
"codebase_coverage": 0.9,
"documentation_coverage": 0.7,
"external_coverage": 0.8
}
}
Anti-Patterns to Avoid
- Spawning agents before reading sources - Always understand context first
- Running agents sequentially when parallelization is possible - Maximize concurrency
- Relying solely on cached documentation - Prioritize current codebase state
- Skipping cache checks - Always check for existing research
- Ignoring historical context - Past decisions inform current understanding
- Over-scoping initial research - Start focused, expand if needed
Example Usage
Basic Research Request
/research "How does the authentication system work in this codebase?"
Advanced Research with Parameters
/research "Analyze payment processing implementation" --scope=codebase --depth=deep
Research from Ticket
/research --ticket="docs/tickets/AUTH-123.md" --scope=both
Follow-Up Commands
After research completes, typical next steps:
/plan- Create implementation plan based on findings/review- Validate research conclusions/work- Begin implementation with full context
Research Quality Checklist
Before finalizing research output:
- All claims have file:line evidence
- Historical context included where relevant
- Open questions explicitly listed
- Recommendations are actionable
- Confidence levels assigned
- Cross-component relationships identified
- Potential risks documented
Research References
This skill incorporates methodologies from:
- Codeflow Research Patterns - Multi-agent orchestration
- Bsharat et al. (2023) - Principled prompting for quality
- Kong et al. (2023) - Expert persona effectiveness
- Yang et al. (2023) - Step-by-step reasoning optimization
Anti-Rationalization Table
| Excuse | Counter |
|---|---|
| "I've found enough, no need to keep searching" | Partial research leads to partial solutions. Multiple sources confirm accuracy. |
| "The codebase is too large to research thoroughly" | Targeted scope definition prevents overwhelm. Focus on the relevant subsystem first. |
| "I'll just start coding and figure it out as I go" | Coding without research repeats past mistakes and ignores existing patterns. |
| "Cached documentation is good enough" | Cached docs may be stale. Current codebase state is the source of truth. |
| "One agent is enough for this research" | Parallel agents provide overlapping validation. Single agents miss blind spots. |
See Also
deep-web-research— For web-focused research with source evaluationresearch-companion— For research with document analysis and fact-checkingprompt-refinement— For structuring research prompts before executionprompt-refinement— For enhancing research agent prompts