research

name	research
description	Answer structured research questions about a codebase using targeted parallel analysis agents, then synthesize findings into a research document in .rpiv/artifacts/research/. Internally dispatches the scope-tracer agent to formulate trace-quality research questions, then answers them. Use when the user wants in-depth research on a codebase area, asks to "research X", or needs answers to architecture or behavior questions before designing changes.
argument-hint	[free-text research prompt]
shell-timeout	10
disable-model-invocation	true
contract	{"produces":{"kind":"produces","meta":{"artifactKind":"research"},"data":{"type":"object","properties":"[Truncated]"}},"consumes":{"meta":{"artifactKind":"[Truncated]"}}}

Research

You are tasked with answering structured research questions by spawning targeted analysis agents and synthesizing their findings into a comprehensive research document. This skill internally dispatches the scope-tracer agent to formulate trace-quality research questions, then answers them.

Input

$ARGUMENTS — free-text research prompt, or a .rpiv/artifacts/discover/*.md path to chain from discover.

Metadata

node "${SKILL_DIR}/../_shared/now.mjs"
echo
node "${SKILL_DIR}/../_shared/git-context.mjs"

Copy values verbatim — do not reformat the timezone offset.

Flow

1. Input → 2. Dispatch agents → 3. Synthesize & checkpoint → 4. Write doc → 5. Present & chain → 6. Follow-ups

The final artifact feeds design or blueprint.

Steps

Step 1: Input Handling

1. Argument is empty:

   Please provide a free-text research prompt.
   

   Then wait for input.

2. Detect chained discover artifact: If the input includes a path matching .rpiv/artifacts/discover/.*\.md, read it FULLY using the Read tool (no limit/offset) before scope-tracer dispatch:

   • Translate each ### [Decision title] block in the FRD's ## Decisions section into a Developer Context entry: **Q (discover: <Decision title>): <Question text>** followed by A: <Chosen text>. Hold these entries in main context — they're recorded in the research artifact's Developer Context section in Step 4 (write document).
   • Use the FRD's ## Recommended Approach text (1-2 sentences naming the architectural shape) as the topic body for the next sub-step's scope-tracer prompt. The full discover artifact path stays in the input so scope-tracer's "read mentioned files first" rule picks up the file naturally for additional context.
   • Carry the FRD's Open Questions forward verbatim into the research artifact's Open Questions section in Step 4.
   • If the input is plain free-text or includes a non-discover path, skip this sub-step and proceed directly to scope-tracer dispatch with the input as the topic.

3. Dispatch the scope-tracer agent to formulate trace-quality research questions for the user's topic:

   Agent({
     subagent_type: "scope-tracer",
     description: "trace scope",
     prompt: "$ARGUMENTS"
   })
   

   The agent reads any mentioned files, sweeps anchor terms via grep/find/ls, reads 5-10 key files for depth, then emits a Discovery Summary + 5-10 dense numbered questions inline in its final message. Nothing is written to disk.

4. Parse the agent's final message as the questions artifact body. Extract: Discovery Summary (3-5 sentence file-landscape overview), Questions (numbered dense 3-6 sentence paragraphs).

   Questions formulated — emit:

   [Questions]: {N} research questions formulated. Reading shared files and grouping before dispatch.
   

5. Read key shared files referenced across multiple questions into main context — especially shared utilities, type definitions, and integration points that multiple questions mention.

6. Analyze question overlap for grouping:

   • Parse all question paragraphs and extract file references from each
   • Identify questions that share 2+ file references — these are candidates for grouping

Step 2: Dispatch Analysis Agents

Spawn analysis agents using the Agent tool — all in a single assistant message with multiple Agent calls (concurrent, synchronous). Never run_in_background: its completion can't re-drive a workflow session, so the skill ends its turn before writing the document and the stage fails with no artifact.

Launch marker — in that SAME assistant message, as its text block (it adds no turn, so the one-message parallel dispatch shape stays intact), emit:

[Dispatched]: {N} analysis agents in one batch{ + precedent sweep}. Waiting for returns.

N counts every dispatched agent, including the git-gated precedent-locator when it joins; the + precedent sweep suffix appears only when it does.

Default agent: codebase-analyzer for all codebase questions. This agent has Read, Grep, Glob, LS — it can trace code paths, find patterns, and analyze integration points.

Exception: External surfaces — third-party APIs, SDKs, libraries, services, protocols, or wire formats — that the codebase doesn't already use → web-search-researcher. Trigger on the surface itself, not on whether the question text literally names "docs" or "API".

Agent prompt — question-as-prompt:

Each agent receives the dense question paragraph(s) directly as its prompt. The question IS the instruction.

For standalone questions (no grouping):

Research topic: {topic from frontmatter}

Answer the following research question thoroughly with file:line references. Read the files mentioned, trace the code paths described, and provide a complete analysis.

{Full dense question paragraph}

Provide your analysis with exact file:line references. Focus on DEPTH — trace the actual code, don't just locate it.

For grouped questions:

Research topic: {topic from frontmatter}

Answer the following related research questions thoroughly with file:line references. These questions share overlapping code paths — use your cross-question context to provide deeper, more connected analysis.

Question 1: {Full dense question paragraph}

Question 2: {Full dense question paragraph}

For each question, provide your analysis with exact file:line references. Note connections between the questions where the same code serves multiple roles. Focus on DEPTH — trace the actual code, don't just locate it.

Precedent sweep (git-gated):

When commit is available (not no-commit), spawn one precedent-locator agent alongside the question agents with prompt: "Find similar past changes involving {list key files from Discovery Summary}. Search git log for commits that touched these files, similar commit messages, and follow-up fixes. Research topic: {original query}."

Findings go into Precedents & Lessons. Otherwise skip and note "git history unavailable" there.

Wait for ALL agents to complete before proceeding.

Once every agent has returned, emit:

[Returned]: {N}/{N} agents returned. Proceeding to synthesis.

Step 3: Synthesize and Checkpoint

Before compiling, emit:

[Synthesizing]: compiling {N} agent reports.

1. Compile findings:

   • Match each agent's response to the question(s) it answered
   • Cross-reference findings across questions — look for patterns, conflicts, and connections
   • Prioritize live codebase findings as primary source of truth
   • Use .rpiv/artifacts/ findings as supplementary historical context
   • Include specific file paths and line numbers
   • Every file:line you emit must be VERIFIABLE against the file at this revision. Before writing a citation, confirm the file exists and the cited line (or range end) is within it — cite what you actually read, never a remembered or guessed range. If you cannot verify a line number, cite the file path alone and omit the :line. Write paths relative to the repo root (packages/billing/src/invoice.ts:NN — not the subdirectory-relative src/invoice.ts:NN, nor the bare invoice.ts:NN) — downstream artifacts inherit your citation form. A fabricated file:line (a range that matches no version of the file) propagates unbacked precision downstream — when the build workflow consumes this research, the slice map that rests on it fails the deterministic citation check at the slice-check gate, so an invented citation only bounces the flow.
   • Build Code References as jump-table entries for the planner, not narrative (file:startLine-endLine format)
   • No multi-line code blocks (>3 lines) — use file:line refs + prose. No implementation recipes — facts only.
   • No artifact summaries — link plans/designs in Historical Context, don't summarize their contents. Research describes current codebase state.

2. Developer checkpoint — grounded questions one at a time:

   • Every ambiguity checkpoint MUST be self-contained: state observed behavior, at least one file:line evidence reference, why the decision matters, and 2-4 concrete decision options in the question or option descriptions. Start with grounded questions referencing real findings with file:line evidence. Ask ONE question at a time, waiting for the answer before the next. Use a ❓ Question: prefix. Each question must pull NEW information from the developer — not confirm what you already found:

   Every question MUST embed at least one file:line reference in the question text — not just in surrounding context. Examples:

   • "❓ Question: src/events/orders.ts:NN-NN has 3 event hooks but no error recovery path. Is there a retry mechanism elsewhere I'm not seeing?"

Step 4: Write Research Document

1. Determine metadata (from the Metadata block above):

   • Filename: .rpiv/artifacts/research/<slug>_<topic>.md — <slug> is the second tab-separated field on line 1 of the Metadata block above; <topic> is a brief kebab-case description.
   • repository: ← repo: label; branch: / commit: ← matching labels (already include no-branch / no-commit fallbacks).
   • date: / last_updated: ← <iso> (first tab-separated field on line 1 of the Metadata block above, offset verbatim).
   • Author: author: from the Metadata block (fallback: unknown).

2. Write the research document — this document is compressed context for a new session. Include everything the planner needs to make architectural decisions without re-researching:

   ---
   date: {Current date and time with timezone in ISO format}
   author: {`author:` from Metadata block}
   commit: {Current commit hash}
   branch: {Current branch name}
   repository: {Repository name}
   topic: "{User's Research Topic}"
   tags: [research, codebase, relevant-component-names]
   status: ready
   last_updated: {Same ISO timestamp as `date:` above}
   last_updated_by: {`author:` from Metadata block}
   ---
   
   # Research: {User's Research Topic}
   
   ## Research Question
   {Original user query from questions artifact}
   
   ## Summary
   {High-level findings answering the user's question}
   
   ## Detailed Findings
   
   ### {Component/Area 1}
   - Finding with reference (`file.ext:line`)
   - Connection to other components
   - Implementation details
   
   ### {Component/Area 2}
   ...
   
   ## Code References
   - `path/to/file.py:NN` — Description of what's there
   - `another/file.ts:NN-NN` — Description of the code block
   
   ## Integration Points
   {All connections to the researched area. Enumerate each consumer, dependency, and wiring point with file:line. Source from the questions artifact's Discovery Summary + new connections found by analysis agents.}
   
   ### Inbound References
   - `path/to/consumer.ext:line` — {What references the component and how}
   
   ### Outbound Dependencies
   - `path/to/dependency.ext:line` — {What the component depends on}
   
   ### Infrastructure Wiring
   - `path/to/config.ext:line` — {DI, routes, events, jobs, middleware}
   
   ## Architecture Insights
   {Patterns, conventions, and design decisions discovered}
   
   ## Precedents & Lessons
   {N} similar past changes analyzed.
   
   ### Precedent: {what was added/changed}
   : `hash` — "message" (YYYY-MM-DD)
   : N files across M layers
     layer/ — what changed
   
   :
   - `hash` — "message" (date) — what went wrong
   
   :
   - .rpiv/artifacts/path/to/doc.md — key lesson extracted
   
   : {one sentence — what to watch out for}
   
   ### Composite Lessons
   - {Composite lesson 1 — most recurring pattern first, with relevant `commit hash` inline}
   - {Composite lesson 2}
   
   ## Historical Context (from `.rpiv/artifacts/`)
   {Links only — one line per doc, no summaries of their contents}
   - `.rpiv/artifacts/something.md` — {one-line description of what this doc covers}
   ## Developer Context
   
   A: {Developer's answer}
   
   ## Related Research
   - {Links to other research documents}
   
   ## Open Questions
   {Only questions NOT resolved during checkpoint}
   

Step 5: Present and Chain

Research document written to:
`.rpiv/artifacts/research/{filename}.md`

{N} questions answered, {M} findings across {K} files.

Please review and let me know if you have follow-up questions.

---

💬 Follow-up: describe the change in chat to append a timestamped Follow-up section to this artifact. Re-run `/skill:research` for a fresh artifact.

**Next step (choose one):**
- `/skill:design .rpiv/artifacts/research/{filename}.md` — iterative design with vertical-slice decomposition (produces design artifact for plan)
- `/skill:blueprint .rpiv/artifacts/research/{filename}.md` — lightweight fast path for smaller tasks; combined design + phased plan in one pass (produces implement-ready plan directly)

> 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.

Step 6: Handle Follow-ups

• Append, never rewrite. Edit the artifact to add a ## Follow-up Research {ISO 8601 timestamp} section. Prior content stays immutable.
• Bump frontmatter. Update last_updated + last_updated_by; set last_updated_note: "Added follow-up research for <brief description>".
• Re-dispatch narrowly. Spawn ≤1–2 fresh analysis agents scoped to the new question. Do NOT re-run the full skill.
• When to re-invoke instead. If scope changed materially (different feature surface, different research target), re-run /skill:research for a fresh artifact. The previous block's Next step: stays valid for the existing artifact.

Important Notes

• Analysis only: This skill answers questions. Question formulation is delegated to the scope-tracer subagent at Step 1.
• Single entry point: Free-text research prompt. Argument substitution is handled by rpiv-args; scope-tracer runs in-band before analysis dispatch.
• Chained from discover: when the input includes a path to a .rpiv/artifacts/discover/*.md artifact, read it FULLY in Step 1 and translate each Decision into a Q (discover: <title>) / A: <Chosen> Developer Context entry. Pass the FRD's Recommended Approach text as the scope-tracer topic. Open Questions carry forward verbatim. The argument-hint stays free-text-only — discover artifact recognition is by path-mention, not by argument-hint widening.
• Grouped dispatch: Related questions are batched per agent based on file overlap. Default agent: codebase-analyzer. This reduces token waste from redundant file reads and lets agents build cross-question context.
• Downstream compatible: Research documents feed directly into design and plan — the same Code References / Integration Points / Architecture Insights sections they expect.
• Agent-message parsing: scope-tracer emits Discovery Summary + numbered Questions inline in its final assistant message; parse the agent's final-message text (no file write).
• Critical ordering: Follow the numbered steps exactly
  • ALWAYS dispatch scope-tracer first (Step 1)
  • ALWAYS analyze question overlap for grouping (Step 1)
  • ALWAYS wait for all agents to complete (Step 2)
  • ALWAYS run developer checkpoint before writing (Step 3)
  • ALWAYS gather metadata before writing (Step 4)
  • NEVER write the document with placeholder values
• Frontmatter consistency: Always include frontmatter, use snake_case fields
• Progress markers are transcript text only: the [Questions]: / [Dispatched]: / [Returned]: / [Synthesizing]: lines are one-line status for the lane console's live tail — never artifact content — and NEVER quote the research document's path in a marker, or anywhere else, before the file is written.