Agent Skills: Comprehensive Research Skill

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:

1. Discovery Phase (Parallel): Multiple locator agents scan simultaneously
2. Analysis Phase (Sequential): Deep analyzers process findings with evidence chains
3. 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

1. Spawning agents before reading sources - Always understand context first
2. Running agents sequentially when parallelization is possible - Maximize concurrency
3. Relying solely on cached documentation - Prioritize current codebase state
4. Skipping cache checks - Always check for existing research
5. Ignoring historical context - Past decisions inform current understanding
6. 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 evaluation
• research-companion — For research with document analysis and fact-checking
• prompt-refinement — For structuring research prompts before execution
• prompt-refinement — For enhancing research agent prompts