# Research Command
You are conducting comprehensive codebase research to document what exists without suggesting changes.
## Core Principle
ONLY document what exists — DO NOT suggest changes, improvements, or critiques.
## Workflow
When the user invokes `/research <topic>`:
### 1. Understand the Research Question
- Read the user's query carefully
- **If the query contains a GitHub issue URL** or a short reference (e.g. `#123`):
- Fetch the issue details using: `gh issue view <number-or-url>` (or `mcp__github__issue_read` if `gh` is unavailable)
- Use the issue title and body as the research question / context
- Include the issue number in the research document frontmatter as `github_issue: <number>`
- **Create a development branch** (only when invoked standalone — when invoked from `/build`, the branch already exists):
1. Check the current branch: `git branch --show-current`
2. If the branch name already starts with the issue number, **skip branch creation**
3. Otherwise, derive the branch name: `<issue-number>-<slugified-issue-title>` (lowercase, kebab-case)
4. Switch to `main`: `git checkout main`
5. Create a linked branch: `gh issue develop <issue-number> --name <branch-name> --checkout`
6. **`gh` unavailable:** use `mcp__github__issue_read` to fetch the issue and create the branch locally with `git checkout -b <issue-number>-<slug>`.
- Otherwise, identify what the user wants to understand about the codebase
### 2. Spawn Parallel Sub-Agents
If needed for broad searches, spawn these agents in parallel:
- **discovery-code** agent — to find relevant files
- **discovery-analyze** agent — for deep analysis of how code works
### 3. Web Research (when needed)
If the research topic involves **external concepts** — statistical distributions, mathematical formulas, numerical algorithms, external references (DLMF, NIST, Wikipedia distribution articles) — use **WebSearch** and **WebFetch** tools to gather context.
**When to do web research:**
- The topic references a distribution not yet in the codebase (find the canonical PDF/CDF formulas)
- The topic involves a numerical algorithm or special function from the literature
- The topic references a statistical test with a specific reference distribution
- The user explicitly asks for external context
**When NOT to do web research:**
- The topic is purely about internal codebase structure or data flow
- The answer is fully derivable from reading the code
### 4. Gather Codebase Information
- Search for relevant files using Glob and Grep tools
- Read and understand key code sections
- Trace data flows and component interactions
- Document patterns and conventions
### 5. Produce Research Document
Create a structured markdown file at:
`thoughts/research/YYYY-MM-DD-HHmm-<topic-slug>.md`
Use this format:
```markdown
---
date: <ISO timestamp>
topic: "<user's research question>"
github_issue: <number, if sourced from a GitHub issue — omit otherwise>
status: complete
---
# Research: <topic>
**Date**: <timestamp>
**Repository**: ranjs
**Branch**: <current branch>
## Research Question
<Original user query, or issue title + body if sourced from GitHub>
## Summary
<High-level findings - 2-3 paragraphs answering the question>
## Detailed Findings
### Component 1: <name>
- **Location**: `src/dist/log-normal.js:23-45`
- **Purpose**: What this component does
- **Key Details**: Important implementation details
- **Connections**: How it connects to other components
### Component 2: <name>
<Similar structure>
## Information Flow
<Diagram or description of how data/control flows through the system>
## Patterns & Conventions
- Pattern 1: Description with examples
- Pattern 2: Description with examples
## Key Files Reference
- `src/dist/_distribution.js` — Base Distribution class
- `src/algorithms/brent.js` — Brent root-finding (used for quantile)
- `src/special/gamma.js` — Gamma function
## External Context
<If web research was performed, summarize key findings here.
Include canonical formulas with citations. Omit if no web research was needed.>
## Sources
<List of external URLs consulted. Omit if no web research was needed.>
- [Source Title](https://example.com)
## Questions for Planning Phase
<Any open questions that need human decision in planning>
```
### 6. Present to User
> "I've completed the research on [topic]. The findings are documented at:
>
> `thoughts/research/YYYY-MM-DD-HHmm-<topic>.md`
>
> Branch: `<branch-name>` (if created from a GitHub issue)
>
> Key findings:
> - <Key finding 1>
> - <Key finding 2>
> - <Key finding 3>
>
> Please review the research document. When you're ready to create a plan, use:
> `/plan <description> — see thoughts/research/YYYY-MM-DD-HHmm-<topic>.md`"
## Rules
### DO:
- Describe what IS, not what SHOULD BE
- Provide precise file:line references
- For new distributions: document the canonical PDF/CDF formula from authoritative sources
- Save everything to `thoughts/research/`
### DO NOT:
- Suggest improvements or changes
- Perform root cause analysis
- Propose future enhancements
- Include subjective opinions or critiques