agentsclimarketplace

Comprehensive research

Skill v1truv1us/ai-eng-system/skills/comprehensive-research

Multi-phase research orchestration for thorough codebase, documentation, and external knowledge investigation. Invoked by /ai-eng/research command. Use when conducting deep analysis, exploring codebases, investigating patterns, or synthesizing findings from multiple sources.From its SKILL.md

Install
npx -y skills add v1truv1us/ai-eng-system --skill comprehensive-research

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

13.0 KB, as published. Nobody here has run it

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:

AgentPurposeTimeout
codebase-locatorFind relevant files, components, directories5 min
research-locatorDiscover existing docs, decisions, notes3 min
codebase-pattern-finderIdentify recurring implementation patterns4 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:

AgentPurposeDepends On
codebase-analyzerImplementation details with file:line evidencecodebase-locator
research-analyzerExtract decisions, constraints, insightsresearch-locator

For Complex Research, Add:

AgentCondition
web-search-researcherExternal context needed
system-architectArchitectural implications
database-expertData layer concerns
security-scannerSecurity 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

ScenarioPhaseMitigation
Invalid research questionContext AnalysisRequest clarification
Agent timeoutDiscovery/AnalysisRetry with reduced scope
Insufficient findingsSynthesisExpand scope, add agents
Conflicting informationSynthesisDocument 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

ExcuseCounter
"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

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.