rpi-research

name	rpi-research
description	Research and document a codebase for a specific topic using parallel sub-agents. Use when the user wants to investigate, understand, or map out how something works in the codebase, or asks to "research" a topic.
tools	Bash, Read, Glob, Grep, Task
priority	high

YOUR ONLY JOB: DOCUMENT THE CODEBASE AS IT EXISTS TODAY

• DO NOT suggest improvements or changes
• DO NOT critique the implementation
• ONLY describe what exists, where it exists, and how it works
• You are creating a technical map, not a code review

Skill Priority and Deduplication

• rpi-research is the canonical research skill for RPI workflows
• Do not layer another general research skill on top of the same query
• Escalate to non-rpi-* specialist skills only for truly domain-specific depth

---

MANDATORY WORKFLOW - EXECUTE IN ORDER:

STEP 1: Read Mentioned Files First

If the user mentions specific files, read them FULLY before anything else.

STEP 2: Decompose the Research Question

Break down the query into 3-5 specific research areas.

STEP 3: SPAWN PARALLEL SUB-AGENTS (REQUIRED)

Launch multiple Task agents in parallel to do the research:

• rpi-codebase-locator agent: Find WHERE files and components live (use Glob/Grep)
• rpi-codebase-analyzer agent: Understand HOW specific code works (use Read)
• rpi-pattern-finder agent: Find examples of existing patterns (use Grep)

Call multiple agents in parallel. Example:

I'll spawn 3 parallel research tasks:
1. rpi-codebase-locator: "MCP extension loading"
2. rpi-codebase-analyzer: "extension configuration files"
3. rpi-pattern-finder: "how other extensions are structured"

DO NOT skip this step. DO NOT do all the research yourself. USE PARALLEL AGENTS.

STEP 4: Wait for All Results

Wait for ALL agent tasks to complete before proceeding. Compile and connect findings across components.

STEP 5: Gather Git Metadata

Run these commands:

date +"%Y-%m-%dT%H:%M:%S%z"
git rev-parse HEAD
git branch --show-current
basename "$(git rev-parse --show-toplevel)"

If git metadata commands fail (for example, not a git repo), continue and set:

• git_commit: unknown
• branch: unknown
• repository: [basename of current working directory]

STEP 6: Write Research Document

Create _scratchpad/research/YYYY-MM-DD-HHmm-topic.md (e.g., 2025-01-15-1430-auth-flow.md) with this structure:

---
date: [ISO date from step 5]
git_commit: [commit hash or unknown]
branch: [branch name or unknown]
repository: [repo name or cwd basename]
topic: "[Research Topic]"
tags: [research, codebase, relevant-tags]
status: complete
---

# Research: [Topic]

## Research Question
[Original query]

## Summary
[High-level findings]

## Detailed Findings

### [Component 1]
- What exists (file:line references)
- How it connects to other components

## Code References
- `path/to/file.py:123` - Description

## Open Questions
[Areas needing further investigation]

STEP 7: Present Summary

Show the user a concise summary with key file references. Ask if they have follow-up questions.

---

REMEMBER:

• Use parallel agents for research, not sequential tool calls
• Document what IS, not what SHOULD BE
• Include specific file:line references
• Write the research doc to _scratchpad/research/
• Do not fail the workflow solely because git metadata is unavailable