Research Codebase

---
name: research-codebase
description:
  "Conduct comprehensive codebase research using parallel sub-agents. **ALWAYS use when** the user
  asks to 'research', 'investigate', 'explore the codebase', 'how does X work', 'find out about', or
  needs deep analysis of how existing code is structured. Produces a research document in
  thoughts/shared/research/ with file:line references."
disable-model-invocation: false
allowed-tools:
  Read, Write, Grep, Glob, Task, TodoWrite, Bash,
  mcp__serena__activate_project, mcp__serena__list_memories, mcp__serena__read_memory,
  mcp__serena__get_symbols_overview, mcp__serena__find_symbol, mcp__serena__find_referencing_symbols,
  mcp__serena__search_for_pattern, mcp__serena__find_file, mcp__serena__list_dir
version: 1.0.0
---

# 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

```bash
# 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

```bash
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:

```bash
# 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 `Grep`s, 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:**

```bash
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:

```markdown
---
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 benefit from further investigation}

## Related Documents

{List related thoughts documents using wiki-links, e.g.:}

- [[YYYY-MM-DD-source-ticket|Source Ticket]]
- [[YYYY-MM-DD-related-research|Related Research]]
```

### Step 7: Add GitHub permalinks (if applicable)

- If on main/master or commit is pushed, generate GitHub permalinks: `https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}`
- If on unpushed feature branch, keep local file references

### Step 8: Sync, track, and present findings

**MANDATORY — do all three sub-steps before presenting results to the user.**

**8a. Sync thoughts:**

```bash
humanlayer thoughts sync
```

**8b. Linear comment** (if ticket detected): Add a comment noting research is complete and linking the document path. Use Linearis CLI (run `linearis comments usage` for syntax).

**8e. Present summary to user:**

```
Research complete!

**Research document**: {exact file path you wrote}

**Summary**: {2-3 sentence summary}

**Key files**: {Top 3-5 file references}

Would you like me to:
1. Dive deeper into any specific area?
2. Explore related topics?
```

**End session tracking:**

```bash
if [[ -n "${CATALYST_SESSION_ID:-}" && -x "$SESSION_SCRIPT" ]]; then
  "$SESSION_SCRIPT" end "$CATALYST_SESSION_ID" --status done
fi
```

**STOP HERE. Do NOT offer to create plans, use EnterPlanMode, or start implementing. Research is complete.**

### Step 9: Handle follow-up questions

If the user has follow-up questions:

- DO NOT create a new research document - append to the same one
- Update frontmatter: `last_updated`, `last_updated_by`, add `last_updated_note`
- Add new section: `## Follow-up Research: {Question}`
- Spawn new sub-agents as needed
- Re-sync thoughts

## Important Notes

- **NEVER use EnterPlanMode or create implementation plans** — that's `/create_plan`'s job
- ALWAYS use parallel Task agents - spawn all at once, then wait for all to complete
- Always perform fresh codebase research - never rely solely on existing docs
- Focus on concrete file paths and line numbers
- Read mentioned files FULLY (no limit/offset) before spawning sub-tasks
- Follow the numbered steps exactly - don't skip or reorder
- `thoughts/searchable/` paths should be documented as `thoughts/shared/` equivalents
- If context exceeds 60% after research, recommend clearing before planning phase

## Linear Integration

State names (`stateMap.*`) come from the `linearis` skill's single-source transition table — not restated here.

If a ticket is detected (provided as argument, mentioned in query, or from context):

- **At research start**: Update ticket status to `stateMap.research` from config using Linearis CLI (run `linearis issues usage` for syntax).
- **After document saved**: Add a comment with the document link — this is an agent-authored comment, so post it through the app actor (`linear-reply.mjs --as <role>`, or the `linear-comment-post.sh` helper), never bare `linearis issues discuss`/`reply` (those post as the human — see the `linearis` skill's "Comment on a ticket" section).
- If the tooling is not available, skip silently and continue research