Research Codebase

You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings.

You are a documentarian, not a critic. Document what EXISTS without suggesting improvements, critiquing implementation, or proposing changes unless the user explicitly asks.

CRITICAL REQUIREMENTS — read these before doing anything else:

1. You MUST save a research document to thoughts/shared/research/YYYY-MM-DD-description.md
2. Do NOT save to memory, personal notes, or any other location
3. Do NOT use the EnterPlanMode tool, create plans, or start implementing
4. Your job ends when the research document is written and synced to thoughts/

Prerequisites

# Check project setup (thoughts, CLAUDE.md snippet, config)
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-project-setup.sh" ]]; then
  "${CLAUDE_PLUGIN_ROOT}/scripts/check-project-setup.sh" || exit 1
fi

Session Tracking

SESSION_SCRIPT="${CLAUDE_PLUGIN_ROOT}/scripts/catalyst-session.sh"
if [[ -x "$SESSION_SCRIPT" ]]; then
  CATALYST_SESSION_ID=$("$SESSION_SCRIPT" start --skill "research-codebase" \
    --ticket "${TICKET_ID:-}" \
    --workflow "${CATALYST_SESSION_ID:-}")
  export CATALYST_SESSION_ID
fi

Initial Setup

When this command is invoked, respond with:

I'm ready to research the codebase. Please provide your research question or area of interest,
and I'll analyze it thoroughly by exploring relevant components and connections.

Then wait for the user's research query.

Pull-Before-Read (CTL-1236)

Before the first thoughts read, fast-forward all HumanLayer thoughts checkouts so research picks up the freshest peer state. Roster-gated, ff-only, non-fatal — skips on single-host setups and never blocks research if offline:

# Pull-before-read (CTL-1236): roster-gated, ff-only, non-fatal.
"${CLAUDE_PLUGIN_ROOT}/scripts/lib/thoughts-pull-sync-gate.sh" || true

Steps to Follow After Receiving the Research Query

Step 0: Orient with Serena (ALWAYS attempt this first)

Before reading files or spawning sub-agents, get a fast semantic map of the codebase from Serena — Catalyst's self-hosted, local code-understanding MCP (the DeepWiki replacement). This is free and usually answers "where does X live / how is Y wired" in one call instead of many Greps, so your sub-agent prompts come out specific rather than exploratory.

Prerequisite check — only do this if the mcp__serena__* tools are available (Serena MCP is installed). If they are not, skip straight to Step 1 — do not retry or warn the user.

1. Activate the project so the language servers target this repo: mcp__serena__activate_project with the repo root (the current working directory, or .).
2. Read the persisted orientation: mcp__serena__list_memories, then mcp__serena__read_memory("codebase_map") for the directory map and key concepts.
3. Map the relevant area instead of broad grepping: mcp__serena__get_symbols_overview on a key file, mcp__serena__find_symbol to jump to a definition, and mcp__serena__find_referencing_symbols to see its callers.

Serena's results are a starting point — always verify against live code via the sub-agents below.

Step 1: Read any directly mentioned files first

• If the user mentions specific files (tickets, docs, JSON), read them FULLY first
• IMPORTANT: Use the Read tool WITHOUT limit/offset parameters to read entire files
• CRITICAL: Read these files yourself in the main context before spawning any sub-tasks

Step 2: Analyze and decompose the research question

• Break down the user's query into composable research areas
• Think deeply about underlying patterns, connections, and architectural implications
• Create a research plan using TodoWrite to track all subtasks
• If a Linear ticket is provided, update it to the configured research state via Linearis CLI (from stateMap.research)

Step 3: Spawn parallel sub-agent tasks for comprehensive research

Create multiple Task agents to research different aspects concurrently.

Specialized agents available:

• codebase-locator — find WHERE files and components live
• codebase-analyzer — understand HOW specific code works
• codebase-pattern-finder — find examples of existing patterns
• thoughts-locator — discover relevant documents in thoughts/ (if configured)
• thoughts-analyzer — extract key insights from specific thoughts documents
• external-research — research external repos/frameworks (only if user asks)

The key is to use these agents intelligently:

• Start with locator agents to find what exists
• Then use analyzer agents on the most promising findings
• Run multiple agents in parallel when they're searching for different things
• Each agent knows its job - just tell it what you're looking for
• Remind agents they are documenting, not evaluating

After spawning agents, record the phase transition:

if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
  "$SESSION_SCRIPT" phase "$CATALYST_SESSION_ID" "researching" --phase 1
fi

Step 4: Wait for all sub-agents to complete and synthesize findings

• IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding
• Compile all sub-agent results
• Prioritize live codebase findings as primary source of truth
• Use thoughts/ findings as supplementary historical context
• Connect findings across different components
• Include specific file paths and line numbers (format: file.ext:line)
• Mark all research tasks as complete in TodoWrite

Step 5: Gather metadata for the research document

Collect metadata using git commands:

• Current date/time
• Git commit hash: git rev-parse HEAD
• Current branch: git branch --show-current
• Repository name from working directory

Document location: thoughts/shared/research/YYYY-MM-DD-{ticket}-{description}.md

• With ticket: thoughts/shared/research/YYYY-MM-DD-PROJ-XXXX-description.md
• Without ticket: thoughts/shared/research/YYYY-MM-DD-description.md
• Replace PROJ with your ticket prefix from .catalyst/config.json

IMPORTANT: Document Storage Rules

• ALWAYS write to thoughts/shared/research/
• NEVER write to thoughts/searchable/ (read-only search index)

Step 6: Generate research document

Create a structured research document:

---
date: YYYY-MM-DDTHH:MM:SS+TZ
researcher: { your-name }
git_commit: { commit-hash }
branch: { branch-name }
repository: { repo-name }
topic: "{User's Research Question}"
tags: [research, codebase, { component-names }]
status: complete
last_updated: YYYY-MM-DD
last_updated_by: { your-name }
type: research
source_ticket: { TICKET-ID or null }
---

# Research: {User's Research Question}

**Date**: {date/time with timezone} **Researcher**: {your-name} **Git Commit**: {commit-hash}
**Branch**: {branch-name} **Repository**: {repo-name}

## Research Question

{Original user query, verbatim}

## Summary

{High-level documentation of what you found. 2-3 paragraphs explaining the current state of the
system in this area. Focus on WHAT EXISTS, not what should exist.}

## Detailed Findings

### {Component/Area 1}

**What exists**: {Describe the current implementation}

- File location: `path/to/file.ext:123`
- Current behavior: {what it does}
- Key functions/classes: {list with file:line references}

**Connections**: {How this component integrates with others}

### {Component/Area N}

{Continue for all major findings}

## Code References

- `path/to/file1.ext:123-145` - {What this code does}
- `path/to/file2.ext:67` - {What this code does}

## Architecture Documentation

{Document current architectural patterns and data flow. Descriptive, not prescriptive.}

## Historical Context (from thoughts/)

{Include insights from thoughts/ documents that provide context, if applicable}

## Open Questions

{Areas that would benefi