---
name: rpi-research
description: "Use when starting the RPI flow and you want to deeply understand a question, system, or feature by reading the codebase before planning."
---

Conduct comprehensive read-only research on a question or feature by dispatching parallel sub-agents and synthesizing findings into a single durable research document.

**RPI principle:** Research documents what **is**. Plan decides what **should change**. Implement performs the **change** and verifies it.

**Announce at start:** "Starting /rpi-research."

## CRITICAL: Documentarian Stance

You and all dispatched sub-agents are documenting **what exists**, not what should exist.

- DO NOT propose changes, fixes, refactors, or improvements unless the user explicitly asks.
- DO NOT critique the implementation, surface "issues", or recommend alternatives.
- DO describe what exists, where, how it works, and how pieces connect.
- DO trace reachability. "X is called by Y" is incomplete — document the chain to a **production entry point** (request handler, scheduler, cron, startup wiring). Whether code runs in production is a fact about what exists, not a critique. Code with no path from an entry point is **dead**, and saying so is documentation.
- DO surface open questions in the artifact's Open Questions section — but as questions, not as veiled critique.

**Don't confuse "don't recommend fixes" (correct) with "don't question whether code runs" (harmful).** Determining that something is dead, unused, or unreachable is documenting what exists — it belongs in the artifact. Only the *prescription* ("so remove it") is out of scope.

This stance is what makes the artifact reusable by `/rpi-plan` (and future readers) without baked-in bias.

## Setup

1. Run `"$SKILL_BASE_DIR/setup.sh" "<slug>"` (extract `<slug>` from `$ARGUMENTS`; everything after the slug is the research query). Parse stdout for `REPO`, `TOPIC_SLUG`, `ARTIFACT_DIR`. `$SKILL_BASE_DIR` is the "Base directory for this skill" path shown at the top of this prompt.
   - If the script exits 2 (`MISSING_SLUG`), use `AskUserQuestion` to ask for a slug, then re-run.

## Pre-flight Validation

- If `<ARTIFACT_DIR>/research.md` already exists, ask the user how to proceed:
  - **Follow-up append** — add a new timestamped section to the existing file
  - **Overwrite** — start fresh
  - **New slug** — re-run Setup with a different slug
  - **Abort** — stop
- If `$ARGUMENTS` after the slug is empty, use ask for the research query inline.

## Process

### Step 1: Parse input and read mentioned files

`$ARGUMENTS` after the slug is the research query. If the query mentions specific files (tickets, docs, JSON, source files), **read them fully** (no `offset`/`limit`) before dispatching any sub-agents. The main context needs full grounding before decomposition.

If the query is solution-shaped ("how should we implement X", "replace A with B"), normalize it into neutral codebase questions before decomposition: what exists, where it is used, how it works, and what patterns already exist. Preserve the original query in the artifact, but dispatch research on the neutralized questions.

A query that asks you to **validate, confirm, or check an existing doc, plan, decision, or proposed solution is solution-shaped** even when phrased as a fact-check ("are these citations right?"). It is the most dangerous shape because it reads as documentary but pulls you toward confirming what you were handed. Re-frame to investigate the underlying problem *independently* — what exists, what is actually used, what the simplest explanation is — and actively seek evidence the existing solution is unnecessary or wrong. Confirming citations is not research.

### Step 2: Decompose into research areas

Break the query into 3-6 composable research areas. Examples:
- "Where does X live?" → `rpi:codebase-locator`
- "How does Y work?" → `rpi:codebase-analyzer`
- "Is there a pattern like Z?" → `rpi:codebase-pattern-finder`
- "What's the history of W?" → `git log` / `git blame` + `mcp__glean_default__search`
- "How do other systems do this?" → `web-search-researcher` (only if external context genuinely helps)

Skip categories that don't apply. Don't pad with research areas that won't change the artifact.

**Always include one altitude-raising area the query did not name** — e.g. "how is this subsystem driven in production today, and what did it replace / what is now legacy?" The query usually arrives at the altitude of the proposed change; the answer that reframes the problem often lives one level up. For any "is X used / can we remove X / is this path live" question, this area is **mandatory**, not optional.

### Step 3: Dispatch parallel sub-agents

In a **single message**, dispatch one `Agent` call per research area. Prefix every sub-agent prompt with the documentarian directive:

> "You are documenting what exists. Do NOT critique, suggest improvements, or perform root-cause analysis. Return file:line references for every claim."

**Codebase routing**:
- `rpi:codebase-locator` — find files/components by name or purpose
- `rpi:codebase-analyzer` — explain how a specific path works
- `rpi:codebase-pattern-finder` — find similar implementations to model after

**External routing:**
- `web-search-researcher` — only when external docs/articles are genuinely needed; instruct it to return links
- Glean (`mcp__glean_default__search`, `mcp__glean_default__read_document`) — for internal docs, tickets, prior decisions

Wait for all sub-agents to complete before synthesizing.

### Step 4: Synthesize findings

- Prioritize live code findings over historical/doc findings as the source of truth.
- Cross-reference: connect findings across components (e.g., "X calls Y at `file.ext:LINE` which then writes to Z").
- **Live/used standard:** for any component you describe as live, used, active, or in-production, name the production entry point and the chain to it. Treat "live" as unproven until traced to ground — never infer it from the existence of a single caller. Apply equal tracing depth to components you expect to be live and ones you expect to be dead. (Asymmetric rigor — going deep only on what you assume is dead — is exactly how dead code gets mislabeled live.)
- Verify file:line references that look suspicious by reading the actual file.
- Identify open questions — things sub-agents couldn't answer or that need human judgment.

### Step 5: Write artifact

Write to `<ARTIFACT_DIR>/research.md` using exactly this structure:

```markdown
---
phase: research
date: <today, YYYY-MM-DD>
researcher: <git config user.name fallback to "unknown">
git_commit: <git rev-parse --short HEAD>
branch: <git branch --show-current>
repo: <REPO from dw-setup.sh>
topic: <TOPIC_SLUG>
status: complete
last_updated: <today, YYYY-MM-DD>
last_updated_note: initial research
---

# Research: <topic title>

## Research Question

<original query, normalized>

## Summary

<3-8 sentence high-level documentation of what exists, answering the question. No "we should" — only "X is", "Y does Z".>

## Detailed Findings

### <Component or Area 1>

- <Description of what exists> (`path/to/file.ext:LINE`)
- <How it connects to other components> (`path:LINE`)
- <Current implementation detail, without evaluation>

### <Component or Area 2>

...

## Code References

- `path/to/file.ext:LINE` — <what is there>
- `another/file.ext:LINE-LINE` — <description of the block>

## Historical Context

<Relevant prior decisions, ticket history, or doc references — cite source. Omit section if none.>

## Open Questions

<Things that require human judgment or that the codebase alone can't answer. Phrased as questions, not critique.>
- <question 1>
- <question 2>

_If no open questions, write: "None — research is complete for the stated question."_
```

### Step 6 (optional): Follow-up append

If the user has follow-up questions in the same session:
- Update frontmatter: bump `last_updated`, append `last_updated_note: "<brief description>"`.
- Append a new section `## Follow-up Research <YYYY-MM-DD HH:MM>` with its own Summary / Detailed Findings / Code References / Open Questions sub-sections.
- Dispatch additional sub-agents as needed; same documentarian directive.

If the follow-up arrives in a fresh conversation, re-run `/rpi-research <slug> <new query>` and choose **Follow-up append** at the pre-flight gate.

## Completion

- Report: artifact path, number of detailed findings sections, count of open questions.
- Instruct: "Review `<path>/research.md`. When ready, run `/rpi-plan <slug>` to turn this into an implementation plan."

## Red Flags

**Stop and reconsider if:**
- A sub-agent returns critique or suggestions instead of documentation — re-dispatch with the documentarian directive made explicit.
- File:line references don't match the actual file — verify by reading; if wrong, dispatch a follow-up.
- The question is actually "how should we" rather than "how does it" — neutralize it into code-answerable research questions before dispatching sub-agents.
- The query is "validate/confirm <existing doc or plan>" — you will drift into confirming citations. Re-open the underlying problem as neutral questions and include at least one disconfirmation angle (what evidence would show the premise is false?).
- Findings only confirm the input premise (you found just line-number drift; every claim "confirmed"). Real investigation of a non-trivial system usually surfaces at least one load-bearing surprise. State what you tried to disprove and why it held — and if you tried nothing, you validated rather than investigated.
- A component is labeled live/used on the strength of a single caller, without the chain to a production entry point — trace it to ground before trusting the label.