| name | research-codebase |
| description | Document the existing codebase exactly as it is today (no suggestions, no fixes). Use as the first phase, before proposing changes. |
Research and document the existing codebase exactly as it is today; no suggestions or evaluations.
Behavior contract
- Only document what exists today; do not suggest improvements, RCA, or future work.
- Provide concrete file paths and line references in findings.
- Read any user-mentioned files fully before decomposing work.
Steps after receiving the research query
- Read directly mentioned files fully.
- Decompose the query into focused research areas and create an internal checklist.
- Explore relevant directories and files in parallel when areas are independent. If necessary, inspect git history for additional context.
- Token discipline (see
.agents/skills/token-discipline/SKILL.md): for broad or deep exploration, delegate the heavy reading to Explore/Agent subagents — one per independent area — and bring back only their findings. The main thread should accumulate conclusions and code references, not raw file contents, so later phases inherit a lean context window.
- Synthesize after all exploration completes; prioritize live code findings over historical docs.
- Produce a structured research document.
- If Linear MCP tools are available, save it as a Linear document.
- Also save a copy to the local
research/ directory for reference during later phases.
Output format
- High-level summary (3-6 sentences)
- Detailed findings grouped by component/area
- Code references in the form
path/to/file.py:123-145
