---
name: researching
description: >-
  Use when you need to understand how an existing codebase works and/or survey
  external prior work (papers, methods, tools) before planning or changing
  something. Traces function call paths, maps module dependencies, searches
  academic papers and documentation, compares library alternatives. Triggers:
  research the codebase, how does X work, where is X implemented, what tools or
  libraries exist for X, prior art on X, has this been done before, survey
  approaches to X.
---

# Researching

Build the context a task needs by investigating the current codebase and/or
external prior art in one pass, then synthesizing a single research document
that feeds planning. Run the internal dimension, the external dimension, or
both.

## Interaction mode

Leans **Collaborative** by default; see `ai-research-workflows:using-research-workflows` for the full protocol.

## Checklist

Work through these in order and track them as tasks. Do not skip the review gates (steps 5, 7, and 8):

1. **Explore context** — the request, existing `docs/rse/specs/` (and legacy `.agents/`) docs, recent commits
2. **Scope** — internal / external / both; what counts as relevant; depth
3. **Propose the research plan** — sub-questions + sources; get a quick OK
4. **Investigate** — run the codebase and/or prior-art pass
5. **Present findings** — in sections; confirm understanding *before* writing anything out
6. **Write the research document** — `docs/rse/specs/research-<slug>.md` from the template
7. **Self-review** — read the written doc with fresh eyes; fix issues inline
8. **User reviews the document** — have them go through the written doc before you move on
9. **Hand off** — point to the next skill

## Process

Scope → plan → investigate → present → write → self-review → user review → hand off.

### 1. Explore context

Read the request. Scan `docs/rse/specs/` (then legacy `.agents/`) for existing research and plan documents
(`research-*.md`, and legacy `prior-art-*.md`). Note recent commits if relevant.

### 2. Scope the question

Establish: the precise question; whether it needs **internal** codebase research,
**external** prior-art research, or **both**; what counts as relevant; and the
desired depth. In Collaborative mode ask one focused question at a time; in
Direct mode infer scope from the request and state it before proceeding.

### 3. Propose the research plan

Before investigating, present the decomposition: the codebase sub-questions you
will trace and/or the prior-art sources and dimensions you will search. Get a
quick OK (Collaborative) or state it and proceed (Direct).

### 4. Investigate

Run the dimension(s) in scope:

- **Codebase pass** — see `references/codebase-research.md`
- **Prior-art pass** — see `references/prior-art-research.md`

Both passes may surface gaps and light, clearly-labeled observations; defer deep
critique and design decisions to planning or validation.

### 5. Present findings

Present synthesized findings in sections (codebase first, then prior art),
confirming understanding as you go. Use `file:line` anchors for code and
citations for external sources.

### 6. Write the research document

Derive a slug (lowercase, hyphenated). Read the template:
`assets/research-template.md`. Fill the sections that apply and write to
`docs/rse/specs/research-<slug>.md`. Omit sections for any dimension not investigated.

If the internal pass ran, record the codebase state you researched against —
the commit SHA (`git rev-parse --short HEAD`) and the date — so `file:line`
findings can be re-checked as the code evolves.

### 7. Self-review

Before showing the document, read it through with fresh eyes and fix issues inline:

- **Placeholders** — no "TBD"/"TODO", empty sections, or vague findings.
- **Anchors & citations** — every codebase finding cites a `file:line`; every prior-art claim cites a source.
- **Consistency & coverage** — sections don't contradict, the synthesis matches the findings, and every scoped sub-question is answered (or its gap is named).

Confirm the doc meets the Quality checklist below.

### 8. User reviews the document

Surface the written document and let the user go through it before you move on:

> Research doc written to `docs/rse/specs/research-<slug>.md`. Please review it and tell me if anything is missing or off before we move on to planning.

In Collaborative mode, wait for their response; if they request changes, revise and re-run the self-review. In Direct mode, present the doc and proceed, noting it is ready for their review.

### 9. Hand off

Point to the next skill — usually `ai-research-workflows:planning-implementations`
(or `ai-research-workflows:running-experiments` when an approach is uncertain).

## Common Mistakes

- **Researching both dimensions when one suffices** — scope first; don't search external prior art for a question that is purely about current code, or vice-versa.
- **Uncited prior-art claims** — every external factual claim needs a primary-source citation; label secondary sources as such.
- **Vague codebase findings** — every code finding cites a specific `file:line`; "it's somewhere in auth" is not a finding.
- **Skipping the disconfirming search** — for prior art, actively search for limitations, critiques, and failures, not just supporting evidence.
- **Turning research into a rewrite plan** — surface gaps and light observations, but defer detailed design and critique to planning/validation.

## Quality checklist

- [ ] Scope (internal / external / both) was established and stated
- [ ] Codebase findings carry `file:line` references (if the internal pass ran)
- [ ] Every prior-art claim is cited and ≥1 disconfirming search ran (if the external pass ran)
- [ ] Synthesis connects findings and names gaps
- [ ] Codebase state recorded (commit SHA + date) if the internal pass ran
- [ ] Template used; saved to `docs/rse/specs/research-<slug>.md`
- [ ] Document is self-contained
- [ ] Findings presented before writing; written doc self-reviewed and offered for user review before hand-off
- [ ] Next skill suggested

## Cross-references

- Feeds `ai-research-workflows:planning-implementations`.
- For comparing uncertain approaches with real code, use `ai-research-workflows:running-experiments`.
- Surveyed automatically by `ai-research-workflows:using-research-workflows`.