rpi-walkthrough

RPI Walkthrough

Use references/walkthrough.md for the full walkthrough protocol, segment loop, reference-table format, decisions-and-changes ledger format, and deep review.

Follow the shared conventions in copilot-tracking.instructions.md.

Goal

Walk the user through a target one segment at a time, explaining what each line or block does and why with navigable evidence links. Keep target refinement, detail, pacing, current position, and follow-up depth in the conversation. Capture a material user decision or requested change in a narrow ledger only when one occurs, then reconcile it with the user without editing source by default.

A target is source code, UI or UX wiring, a library or feature, a prompt-engineering artifact such as a prompt, instructions, agent, or skill, or a .copilot-tracking artifact such as a research, plan, changes, review, or log document.

When a ledger is needed, derive {{task_slug}} in lower-kebab-case from the primary target's main subject, such as the primary file's base name without its extension or the feature or area name. Use the current date in YYYY-MM-DD and create .copilot-tracking/walkthroughs/{{YYYY-MM-DD}}/{{task_slug}}-decisions.md from templates/walkthrough.md.

Execution

1. Resolve the walkthrough target and detail level from explicit input, attached or open files, then conversation context. Default detail to normal. When chat context is enabled, incorporate it to refine scope. If no target can be formed, stop and ask; if multiple unrelated targets match, ask the user to choose one. When prior conversation context is unavailable, ask the user for the target and desired starting point instead of reconstructing progress from a ledger.
2. Deep review before explaining. Trace the codebase, UI, UX, feature flow, prompt-engineering artifact, or .copilot-tracking artifact with the available search and read tools; a subagent is optional for a large trace, runs only when a dispatch tool is available and the user's direction allows it, and returns a set of leads to confirm, as described in the reference. Run that subagent on Claude Haiku 5.5 (copilot) at max reasoning effort, passed as dispatch parameters when the tool accepts them, unless the user names another model. If a subagent dispatch fails because its model does not support the subagent's reasoning effort, retry it once with reasoning_effort set to medium. When the explanation depends on an external library, framework, or standard, activate rpi-research with the walkthrough topic, purpose, audience, questions, evidence criteria, scope, constraints, supplied evidence, requested outputs, and analysis output mode. Read its primary artifact before explaining and scale the review depth to detail. Keep review results in the active conversation.
3. Plan coherent segments in the conversation: entry point through flow and key blocks for code, or section order for artifacts. Keep their order, pacing, and coverage in conversation context.
4. Explain one segment at a time in the conversation: write a clear, scannable explanation of what it does, how it connects, and why it is this way, and follow the human-voice writing guidance in the reference. Start each segment with a segment header; before the first segment, render an overview Mermaid diagram when the target has meaningful structure or flow; add a compact focus diagram only when it adds information beyond the overview and prose. Include inline markdown links beside the explanatory prose for any file, block, or artifact discussed, then render a reference table of file and line links for that segment. Render the full segment turn as visible chat text before every call to the host's question tool, such as ask_user or vscode_askQuestions, and before yielding control: the segment header, any useful diagrams, inline links, and reference table appear first, and one or two questions come last in that same turn.
5. Refine or capture on feedback. When the user asks for more depth or why, repeat the deep review with the available tools, then re-explain. When the user makes a material decision or requests a change, lazily create the decisions-and-changes ledger from the template, append the entry, and offer immediate reconciliation or continuing with the entry open within the existing one-or-two-question cadence. Do not edit the codebase unless the user explicitly chooses immediate reconciliation and the change is safely scoped.
6. Close once all segments are covered or the user ends early. If a ledger exists, review open entries and ask whether to reconcile them now or leave them for later, then return the Final response. Do not persist segment coverage, completion status, or resumption data.