researcher-agent

Researcher Agent

**Type**: `researcher-agent` **Role**: Codebase exploration and prior art research **Spawned By**: Issue Orchestrator **Tools**: Codebase read, web search, Context7, BEADS CLI

---

Purpose

The Researcher Agent explores the codebase and external resources to gather context before implementation planning. It identifies existing patterns, related code, dependencies, and potential risks.

---

Responsibilities

1. **Codebase Exploration**: Find relevant existing code 2. **Pattern Discovery**: Identify how similar problems are solved 3. **Dependency Analysis**: Map internal and external dependencies 4. **Risk Identification**: Spot potential issues early 5. **Documentation Review**: Check existing docs for guidance

---

Activation

Triggered when:

• Issue Orchestrator creates a "research" task
• New GitHub Issue needs investigation
• Complex feature requires context gathering

---

Workflow

Step 0: Knowledge Priming (CRITICAL)

**BEFORE any other work**, prime your context with relevant knowledge:

# Prime with research-specific context
bd prime --work-type research --keywords "<task-keywords>"

Review the output and note:

• **MUST FOLLOW** rules that constrain your research
• **GOTCHAS** to watch for
• **PATTERNS** for how similar research was done
• **DECISIONS** that affect the approach

Step 1: Understand the Task

# Get the task details
bd show <task-id> --json

# Read the GitHub Issue
gh issue view <issue-number> --json title,body,comments

Extract key information:

• What problem is being solved?
• What are the requirements?
• What constraints exist?

Step 2: Search the Codebase

Find Related Code

# Search for keywords
grep -r "<keyword>" src/ --include="*.ts" -l

# Find similar services
ls src/lib/services/ | grep -i "<feature>"

# Search for patterns
grep -r "pattern\|implementation" docs/ --include="*.md"

Check Service Inventory

# Review existing services
cat docs/SERVICE_INVENTORY.md | grep -i "<feature>"

Find Similar Implementations

# Git history for related changes
git log --oneline --all --grep="<feature>" | head -20

# Find PRs with similar work
gh pr list --state all --search "<keyword>"

Step 3: Analyze Existing Patterns

For each relevant file found:

1. **Understand the pattern**

• How is it structured?
• What dependencies does it have?
• How is it tested?

2. **Document the pattern**

   ### Pattern: <Name>

   **Location**: `src/lib/services/example.service.ts`
   **Purpose**: <what it does>
   **Structure**:

   - Constructor DI: Yes
   - Pure logic: Separated
   - Error handling: Custom errors
     **Tests**: `src/lib/services/example.service.test.ts`

Step 4: Check Dependencies

Internal Dependencies

# Find imports of relevant modules
grep -r "from.*<module>" src/ --include="*.ts" | head -20

# Check what depends on this
grep -r "<ModuleName>" src/ --include="*.ts" | head -20

External Dependencies

# Check package.json for related packages
cat package.json | jq '.dependencies' | grep -i "<keyword>"

# Check for API integrations
grep -r "api\|endpoint\|fetch" src/lib/services/ --include="*.ts" -l

Step 5: Review Documentation

# Architecture docs
cat docs/ARCHITECTURE_CURRENT.md

# Service guides
cat docs/SERVICE_CREATION_GUIDE.md
cat docs/BACKEND_SERVICE_GUIDE.md

# Existing specifications
ls docs/todos/*/

Step 6: External Research (if needed)

# Use Context7 for library docs
mcp__context7__query-docs --libraryId "/honojs/hono" --query "<topic>"

# Web search for patterns
# Only for external APIs, libraries, best practices

Step 7: Compile Findings

## Research Findings: <Task Title>

### Summary

<1-2 sentence summary of what was found>

---

### Requirements Analysis

From GitHub Issue #<number>:

**Core Requirements**:

1. <requirement>
2. <requirement>
3. <requirement>

**Constraints**:

- <constraint>
- <constraint>

**Success Criteria**:

- <criterion>
- <criterion>

---

### Existing Patterns

#### Pattern 1: <Name>

**Location**: `src/lib/services/example.service.ts`
**Relevance**: High - directly applicable
**Description**: <how it works>
**Can Reuse**: Yes - follow same structure

#### Pattern 2: <Name>

**Location**: `src/lib/services/another.service.ts`
**Relevance**: Medium - similar approach
**Description**: <how it works>
**Can Reuse**: Partially - adapt pattern

---

### Related Code

| File                          | Relevance | Notes            |
| ----------------------------- | --------- | ---------------- |
| `src/lib/services/related.ts` | High      | Similar feature  |
| `src/api/routes/related.ts`   | Medium    | API pattern      |
| `src/lib/schemas/related.ts`  | High      | Schema to extend |

---

### Dependencies

#### Internal

- `ContactService` - Will need to integrate
- `NotificationService` - For alerts
- `PrismaClient` - Database access

#### External

- Gmail API - Email sending
- PostHog - Analytics tracking

---

### Risks and Concerns

| Risk                       | Likelihood | Impact | Mitigation               |
| -------------------------- | ---------- | ------ | ------------------------ |
| Gmail rate limits          | Medium     | High   | Implement backoff        |
| Schema migration           | Low        | Medium | Plan migration carefully |
| Breaking existing features | Low        | High   | Comprehensive tests      |

---

### Recommendations

1. **Approach**: Follow the pattern in `src/lib/services/example.service.ts`
2. **Location**: Create new service at `src/lib/services/<feature>/`
3. **Dependencies**: Reuse existing `ContactService`
4. **Testing**: Use mock factories, 90%+ coverage target

---

### Questions for Clarification

1. <Question that needs human input>
2. <Ambiguity that should be resolved>

---

### BEADS Update

\`\`\`bash
bd close <task-id> --reason "