researcher

Researcher (Track 2 — Phase 1)

Purpose

Gather information needed to write a design document. Output goes to workspace/research/<topic>.md for the planner to consume.

Process

Step 1: Define Research Questions

Before searching, identify 3-5 specific questions that need answering:

• How does the existing system handle X?
• What patterns are used for Y?
• What dependencies exist around Z?
• What are the constraints?

Step 2: Local Search (PTC)

Run local codebase search first:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/researcher/scripts/search_local.py <term1> <term2> [--pattern "*.py"]

This returns a JSON summary of matches. Read only the most relevant files identified.

Step 3: Parallel Sub-Agent Research (if needed)

If local search is insufficient, spawn Explore sub-agents for deeper investigation. Each agent gets a fresh context window — no context bleed.

Spawn agents for INDEPENDENT questions in parallel (single message, multiple Agent calls):

Agent(subagent_type="Explore", prompt="Research question 1: ...")
Agent(subagent_type="Explore", prompt="Research question 2: ...")

Each agent should:

• Focus on ONE specific question
• Return a structured summary (not raw code dumps)
• Stay under 5 minutes of exploration

Step 4: External Docs (if needed)

For library/framework documentation, use context7 MCP:

• Batch queries — never query per-line
• Only after local search is insufficient

Step 5: Synthesize

Aggregate findings into a research summary:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/researcher/scripts/format_findings.py \
  --topic "<topic>" --output "workspace/research/<topic>.md"

The script reads findings from stdin (JSON) and writes formatted markdown.

Step 6: Present

Write the research file and show the user:

• Key findings (3-5 bullet points)
• Open questions (if any)
• Recommendation: "Ready for /plan" or "Need more research on X"

Examples

Example 1: Auth System Research

Input: "/research authentication flow" Process:

1. search_local.py "auth" "login" "session" "token"
2. Read key files from results
3. Spawn Explore agent: "How does session management work?"
4. Spawn Explore agent: "What auth middleware exists?"
5. Synthesize to workspace/research/authentication-flow.md

Example 2: API Research

Input: "/research api error handling patterns" Process:

1. search_local.py "error" "exception" "handler" --pattern "*.py"
2. Read 3-4 most relevant files
3. No sub-agents needed (local search sufficient)
4. Synthesize to workspace/research/api-error-handling.md

Anti-Patterns

• Do NOT dump entire files into context (read only relevant sections)
• Do NOT spawn sub-agents for simple questions answerable by grep
• Do NOT skip the PTC local search step
• Do NOT research and plan in the same session (research writes to disk, then STOP)