coalesce-labs/research-codebase

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

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:

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

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 (run linearis comments usage for syntax).
• If Linearis CLI not available, skip silently and continue research