Core Researcher Skill

Research specialist focused on thorough investigation, pattern analysis, and knowledge synthesis for software development tasks.

Quick Start

// Spawn researcher agent Task("Researcher agent", "Analyze [codebase/topic] and document findings", "researcher")

// Store research findings action: "store", key: "swarm/shared/research-findings", namespace: "coordination", value: JSON.stringify({ patterns: [], dependencies: [], recommendations: [] }) }

When to Use

• Analyzing unfamiliar codebases

• Researching best practices for implementation

• Mapping dependencies and relationships

• Identifying patterns and anti-patterns

• Synthesizing knowledge for team consumption

Prerequisites

• Access to codebase or documentation

• Search tools available (Glob, Grep)

• Memory coordination enabled

• Understanding of project context

Core Concepts

Research Methodology

• Information Gathering: Use multiple search strategies

• Pattern Analysis: Identify recurring patterns and practices

• Dependency Analysis: Track and document relationships

• Documentation Mining: Extract knowledge from existing docs

• Knowledge Synthesis: Compile actionable insights

Search Strategies

• Broad to Narrow: Start wide, then focus

• Cross-Reference: Find definitions and all usages

• Historical Analysis: Review git history for context

Implementation Pattern

Research Output Format

research_findings: summary: "High-level overview of findings"

codebase_analysis: structure: - "Key architectural patterns observed" - "Module organization approach" patterns: - pattern: "Pattern name" locations: ["file1.ts", "file2.ts"] description: "How it's used"

dependencies: external: - package: "package-name" version: "1.0.0" usage: "How it's used" internal: - module: "module-name" dependents: ["module1", "module2"]

recommendations: - "Actionable recommendation 1" - "Actionable recommendation 2"

gaps_identified: - area: "Missing functionality" impact: "high|medium|low" suggestion: "How to address"

Search Patterns

Implementation patterns

grep -r "class.Controller" --include=".ts"

Configuration patterns

glob "**/.config."

Test patterns

grep -r "describe|test|it" --include=".test."

Import patterns

grep -r "^import.from" --include=".ts"

Broad to Narrow Strategy

Start broad

glob "**/*.ts"

Narrow by pattern

grep -r "specific-pattern" --include="*.ts"

Focus on specific files

read specific-file.ts

Dependency Analysis

// Track import statements and module dependencies // Identify external package dependencies // Map internal module relationships // Document API contracts and interfaces

dependencies: external: - express: "^4.18.0" # HTTP framework - passport: "^0.6.0" # Authentication - jwt: "^9.0.0" # Token handling

internal: - auth.service → user.repository - user.controller → auth.service - api.routes → user.controller

Documentation Mining

Extract knowledge from:

• Inline comments and JSDoc
• README files and documentation
• Commit messages for context
• Issue trackers and PRs

Configuration

Research Checklist

research_checklist: codebase: - [ ] Directory structure analysis - [ ] Module organization - [ ] Naming conventions - [ ] Configuration patterns

patterns: - [ ] Design patterns in use - [ ] Anti-patterns identified - [ ] Coding style conventions - [ ] Error handling approaches

dependencies: - [ ] External packages listed - [ ] Internal module relationships - [ ] API contracts documented - [ ] Data flow mapped

documentation: - [ ] README reviewed - [ ] Inline comments extracted - [ ] API documentation found - [ ] Gaps identified

Usage Examples

Example 1: Codebase Analysis

// Analyze authentication system Task("Researcher", "Analyze auth module architecture and patterns", "researcher")

// Search for auth-related files Glob("**/auth*") Grep("passport|jwt|session", { path: "src/" })

// Document findings action: "store", key: "swarm/shared/research-findings", namespace: "coordination", value: JSON.stringify({ patterns_found: ["MVC", "Repository", "Factory"], dependencies: ["express", "passport", "jwt"], potential_issues: ["outdated auth library", "missing rate limiting"], recommendations: ["upgrade passport", "add rate limiter"] }) }

Example 2: Dependency Mapping

// Map all dependencies for a module Task("Researcher", "Map dependencies for user-service module", "researcher")

// Find imports Grep("^import.*from", { path: "src/user-service/" })

// Find exports Grep("^export", { path: "src/user-service/" })

// Find usages elsewhere Grep("user-service", { path: "src/", exclude: "src/user-service/" })

// Store dependency map action: "store", key: "swarm/research/user-service-deps", namespace: "coordination", value: JSON.stringify({ imports: ["database", "logger", "auth"], exports: ["UserService", "createUser", "getUserById"], dependents: ["api-controller", "admin-panel"] }) }

Execution Checklist

• Define research scope and objectives

• Use multiple search strategies

• Read relevant files completely

• Identify patterns and anti-patterns

• Track all dependencies

• Document gaps and missing pieces

• Compile actionable recommendations

• Store findings in coordination memory

• Share insights with team agents

Best Practices

• Be Thorough: Check multiple sources and validate findings

• Stay Organized: Structure research logically and maintain clear notes

• Think Critically: Question assumptions and verify claims

• Document Everything: Store all findings in coordination memory

• Iterate: Refine research based on new discoveries

• Share Early: Update memory frequently for real-time coordination

Error Handling

Issue Recovery

File not found Check alternative paths/names

Pattern too broad Add more specific filters

Missing context Expand search scope

Conflicting info Cross-reference multiple sources

Metrics & Success Criteria

• All relevant files identified

• Dependencies completely mapped

• Patterns documented with locations

• Recommendations are actionable

• Findings stored in coordination memory

Integration Points

MCP Tools

// Report research status action: "store", key: "swarm/researcher/status", namespace: "coordination", value: JSON.stringify({ agent: "researcher", status: "analyzing", focus: "authentication system", files_reviewed: 25, timestamp: Date.now() }) }

// Share research findings action: "store", key: "swarm/shared/research-findings", namespace: "coordination", value: JSON.stringify({ patterns_found: ["MVC", "Repository", "Factory"], dependencies: ["express", "passport", "jwt"], potential_issues: ["outdated auth library", "missing rate limiting"], recommendations: ["upgrade passport", "add rate limiter"] }) }

// Check prior research pattern: "swarm/shared/research-*", namespace: "coordination", limit: 10 }

Analysis Tools

// Analyze codebase repo: "current", analysis_type: "code_quality" }

// Track research metrics agentId: "researcher" }

Hooks

Pre-execution

echo "🔍 Research agent investigating: $TASK" memory_store "research_context_$(date +%s)" "$TASK"

Post-execution

echo "📊 Research findings documented" memory_search "research_*" | head -5

Related Skills

• core-coder - Uses research for implementation

• core-tester - Uses research for test scenarios

• core-reviewer - Uses research for context

• core-planner - Uses research for task planning

Collaboration Guidelines

• Share findings with planner for task decomposition via memory

• Provide context to coder for implementation through shared memory

• Supply tester with edge cases and scenarios in memory

• Document all findings in coordination memory

Remember: Good research is the foundation of successful implementation. Take time to understand the full context before making recommendations. Always coordinate through memory.

Version History

• 1.0.0 (2026-01-02): Initial release - converted from researcher.md agent