---
name: research-codebase
description: Comprehensive codebase research that scales effort to task complexity, synthesises findings, and writes a timestamped document to docs/research/. Use when user says /research-codebase, asks to research or document a codebase area, or wants a deep-dive into how something works.
argument-hint: "<area or question to research>"
---

# Research Codebase

Read-only codebase research. Documents what EXISTS — no recommendations or critiques unless explicitly asked.

## Contract (stated once)

- ONLY describe what exists, where it exists, how it works, and how components interact
- Do NOT suggest improvements, critique implementation, or propose changes
- You are creating a technical map of the existing system

## When invoked without a query

Respond: "I'm ready to research the codebase. What area or question should I investigate?" — then wait.

## Steps

### 1. Read mentioned files

If the user references specific files, read them directly in the **main context** before anything else.

### 2. Scope the tech stack

Detect from `package.json`, config files, directory structure, and project conventions. This determines which reference files are relevant — do NOT load unrelated framework guidance.

### 3. Size the task → choose effort tier

| Tier | When | Agent strategy |
|------|------|----------------|
| **Small** | Single file/component, narrow question | Read and search directly (glob/grep/read). No delegation. |
| **Medium** | Cross-file, single area (e.g. "how does auth work") | Locate with glob/grep, then read and analyse the hits directly. |
| **Large** | Cross-cutting, multi-area (e.g. "map the entire API layer") | Sweep area-by-area (locate → analyse → find patterns), or delegate areas to parallel `omp team` workers (see `reference/agent-prompts.md`). |

### 4. Research

- Track subtasks in a markdown checklist as you go
- For large: read `reference/agent-prompts.md` for `omp team` worker prompt templates
- **MUST GATE**: Before writing findings, show file:line evidence for every claim

### 5. Synthesise & write document

- Read `reference/template.md` for output format and frontmatter
- Read `reference/permalink.md` if GitHub permalinks are applicable
- Gather git metadata: `date`, `user`, `commit`, `branch`, `repo`
- Write to `docs/research/YYYY-MM-DD-description.md`

### 6. Present findings

Show concise summary to user with key file references. Ask if they have follow-up questions.

### 7. Follow-ups

If the user has follow-ups, read `reference/follow-up.md` for the append protocol.

## Cost/token note

This skill can drive multiple tool calls or long-running output. Use `omp cost [--today] [--session <id>]` for local hook-ledger estimates only; it is not provider billing. Keep injected summaries concise and prefer bounded output when rerunning noisy commands.