research-codebase

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.