| name | rpi-explain |
| description | Walk through a recent diff and explain what changed and why, focusing on non-obvious decisions. Use when user says 'explain the changes', 'walk me through the diff', 'what did we just do?', or 'explain how <feature> was implemented'. |
Explain Implementation
Goal
Generate a diff-scoped walkthrough of an implemented solution, explaining what changed and why — with focus on non-obvious decisions.
Auto-detect the mode from input:
- Artifact path (path to plan, design, or spec) → resolve the artifact chain for context, then walk through the diff
- No arguments → auto-detect changed files from git and explain without artifact context
After the initial walkthrough, enter conversation mode — the user can ask follow-up questions to dig deeper into any part of the changes. When done, offer to save the explanation as an artifact if the user wants it.
Invariants
- If an artifact path is provided, resolve its full chain (plan → design → research) and use as context for attributing rationale (EX-1)
- If no arguments, identify changed files from git and proceed without artifact context (EX-2)
- In no-args mode, search for related designs, plans, or diagnoses matching the diff's topic; cite high-relevance hits as "per the design..." (EX-10)
- If a provided path doesn't exist or has no linked artifacts, proceed with diff-only explanation and note the missing context (EX-3)
- Read all changed files fully before generating explanations — never use limit/offset
- Walk through changes file-by-file, providing a factual summary of what changed in each (EX-4)
- For non-obvious changes, provide explicit callouts explaining the reasoning — inferred from artifacts when available, from code context otherwise (EX-5)
- Clearly distinguish between rationale sourced from artifacts ("per the design...") vs inferred from code context ("based on the surrounding code...") (EX-6)
- Summarize straightforward changes briefly (1-2 sentences) rather than explaining the obvious (EX-7)
- After the walkthrough, invite questions — answer follow-ups by reading additional context as needed
- Do not save an artifact by default — only when the user explicitly requests it (EX-8)
- When saving, scaffold to
.rpi/reviews/ with a descriptive topic (EX-9)
- Include file:line references in all explanations
Principles
- Explain, don't judge — no pass/fail ratings or severity classifications (that's
/rpi:rpi-verify)
- Be interactive — the initial walkthrough is a starting point, not the final word; follow-up questions are expected
- Attribute your sources — when rationale comes from an artifact, cite it; when inferred, say so; when uncertain, flag it
- Scale to the diff — large diffs get grouped by theme; small diffs get file-by-file detail
- Prioritize the non-obvious — mechanical changes (renames, imports, formatting) get a brief mention; design decisions and behavioral changes get thorough explanation
Recommended model: cheap tier, low effort — narrating an existing diff is mechanical. Advisory; see docs/model-routing.md.
