rpi

# RPI ## Goal Coordinate a resumable RPI session through Research, Plan, Implement, Review, and Follow-up, whether invoked directly as `/rpi`, discovered by the model for multi-phase RPI coordination, or preloaded by `RPI Agent`. Own task identity, mode, durable session state, phase transitions, and child-task selection. Activate the matching phase skill for its work rather than reproducing its procedure. ## Success criteria * Task identity is resolved before recovery and remains stable across state and phase artifacts; unrelated state is left unchanged. * Progression and decision participation follow confirmed direction. Manual phases wait for explicit advancement; automatic sessions resume the recorded phase and continue within their persisted boundary without routine approvals. * A stop before Implementation completes Plan gates, returns to manual Plan, and walks the user through the research and plan. Research and Planning can be refined here; Implementation waits for an explicit request. * State transitions are durably recorded, task completion remains distinct from session completion, and canonical artifacts govern recovery. * Every task a conversation works on keeps its state in one session folder, parent and child state files link to each other, and an offered canvas shows the session without ever blocking it. * A session runs at most one plan critique and one post-implementation Review, both in its first task, unless the user asks for more; plan changes and review-driven child loops do not start another. The user can skip either step, and a skipped step is recorded as skipped rather than failed. Starting a child task does not bypass unresolved required findings, missing evidence, safety confirmations, or human review. * Phase skills own their canonical evidence and gates; the session preserves their state and artifact pointers across transitions. * Follow-ups stay current and evidence-grounded across parent and child tasks. Through-Review automatic sessions select required in-scope work until acceptance criteria are met, honoring retained selection and stopping without manufacturing optional work. * Phase-aware updates and closeout identify current status, evidence, blockers, and the eligible next action using the Response contract. ## Conversation guidance Follow the active phase skill's opening, material-update, decision walkthrough, closeout, and compaction guidance. Use the completed Review skill's conversation contract during Follow-up. Apply these session-specific additions: * Announce phase and child-loop transitions with their eligibility, material decisions, evidence links, and blockers. Do not repeat the phase's findings or narrate low-level actions. * For every question, including mode selection, use the host's question tool (`ask_user` in Copilot, or `vscode_askQuestions` when exposed under that name) when available and keep its freeform answer field enabled so the user can enter a different answer. Use the tool's built-in blank input rather than an empty selectable label. When the tool is unavailable, invite a custom answer alongside the choices in chat and wait. * While an RPI Workflow canvas shows this session, offer `Answered in the canvas` with each question; when the user chooses it, collect their answers with the canvas's `take_feedback` action, without `checkpoint`, before continuing. Also call `take_feedback` with `checkpoint: true` when you change phase, after each task, before you ask a question, and before you end your turn, then handle and read back what it returns before continuing. Without a canvas, skip both. * Before an intake question, exceptional confirmation, or follow-up selection, explain the context, viable choices and consequences, recommendation when supported, blockers, and relevant links. * In manual mode, walk the user through each phase's artifacts at closeout: research findings, the plan, completed implementation and validation, or review results. Explain what matters, decisions, uncertainty, and eligible next steps. Use the question tool to offer refinement or explicit advancement, including skipping Review when advancing past Implement; an answer requesting the next phase authorizes that transition. Do not ask for acknowledgment alone or repeat an already-delivered walkthrough. * Before compaction advice or handoff, bring the session state current and include its pointer with the phase's retained artifact pointers. ## Mode choice Treat clear requests such as "use automatic mode", "full auto", or "automatically iterate with RPI until finished" as mode authorization, not a request to open a questionnaire. Apply the automatic defaults without asking again. A request to "make the decisions" without automatic-progression intent changes decision participation only. Preserve explicitly retained participation and progression limits on resume; a generic automatic request does not erase them. Ask only about a genuinely conflicting or ambiguous preference. When neither the request nor matching recovered state establishes progression intent, ask "How would you like us to work on this?" with these four option labels and descriptions, in order, and the freeform input required by Conversation guidance: 1. "Handle it end to end". "I'll make the decisions and work through Research, Planning, Implementation, Review, and any needed follow-ups until your request is complete." 2. "Keep going, but check with me". "I'll work through all RPI phases and needed follow-ups automatically, asking you when decisions or direction need clarification, until your request is complete." 3. "Research and plan with me". "I'll research and plan, asking you when decisions or direction need clarification. Then I'll walk you through the artifacts and stop before Implementation so we can refine the research and plan together." 4. "Work through each phase with me". "I'll ask about unclear decisions and direction, walk you through the research, plan, implementation, and review artifacts, and wait for you to choose when we move to the next phase." Explain that required safety confirmations, blockers, and human review still apply, and that the plan critique and Review each run once by default unless the user asks to skip them or run more. Choices 1 and 2 continue RPI loops and required in-scope follow-ups until the requested outcome is complete, with choice 2 retaining user input on unclear decisions throughout. Choice 3 returns to manual mode after Planning for a walkthrough and iteration; it waits for an explicit Implementation request. A custom answer can retain decisions in Research only, Plan only, Review, or follow-up selection, and can skip the plan critique or Review. Clarify an ambiguous answer before changing mode, progression boundary, or decision participation. Apply the selected mode through the transition protocol: * Choice 1 sets automatic progression through Review with agent-owned Research, Planning, Review, and follow-up decisions. * Choice 2 retains Research, Planning, Review, and follow-up decisions, with automatic progression through Review. Use confirmed direction for settled choices; ask about unresolved material decisions or unclear direction, not routine phase advancement. Implementation retains the material-decision protocol owned by `rpi-implement`. * Choice 3 retains Research and Planning decisions, leaves Review and follow-up decisions agent-owned, and selects automatic progression with `before-implementation`. If Implement or a later phase has begun, explain that the boundary is already past and ask for direction without changing mode or restarting. * Choice 4 keeps manual progression in the current phase with user-owned decisions and the artifact walkthroughs in Conversation guidance. * Explicit automatic authorization applies choice 1 defaults only to unset preferences. A custom answer retains only the requested decisions and progression limits; preserve earlier explicit preferences unless changed. * On automatic entry, persist scope and preferences, set `session_status` to `running`, and retain `active_phase`. A later participation-only change updates preferences without changing mode or widening the progression boundary. The Full Auto handoff does not authorize exceptional actions or restart Research. ## State contract ### Location Persist each task's state at `.copilot-tracking/rpi-sessions/{{YYYY-MM-DD}}/{{session_slug}}/{{task_slug}}-state.json`. A session is one conversation's RPI work: every task the conversation works on, child loops and unrelated tasks alike, shares one folder dated by the session's first day, and a later conversation that resumes the session continues in it. Research, plan, critique, changes, and review artifacts keep their own dated locations, and state points to them. * When the session starts, choose `session_name`, a short human-readable name for the conversation's work. `{{session_slug}}` is its lowercase hyphenated form, or the first task's slug when there is no name, at most 40 characters; `{{task_slug}}` is at most 60 characters. Cut a longer value at the last hyphen within the cap, or at the cap. The caps keep paths within Windows path limits. The folder keeps its name when the session's purpose drifts. * Never write over a state file whose `task_id` differs from the task being written. When the folder or state path already belongs to other work, append `-2`, `-3`, and so on to the folder name or task slug, shortening the base so the result stays within its cap, and keep that name. ### Stable fields Persist one JSON object with these stable fields: * `task_id` and `task_slug`: strings or `null` when unrecoverable * `session_name`: the session's human-readable name, or `null` when unrecoverable * `parent_task`: `null` when the task does not continue another task; otherwise an object with string-or-null `task_id`, `task_slug`, and `state_path`, the workspace-relative path of the parent's state file * `child_tasks`: an array, in creation order, of objects with string-or-null `task_id`, `task_slug`, and `state_path` for each child; empty until a child exists * `mode`: `manual`, `automatic`, or `null`; `active_phase`: `Research`, `Plan`, `Implement`, `Review`, `Follow-up`, or `null`; `status`: `active`, `blocked`, `completed`, or `null` * `session_status`: `running`, `stopped`, or `null`; keep it distinct from the task `status`, so a completed automatic task can have a running session * `artifact_paths`: an object keyed by `research`, `plan`, `critique`, `changes`, and `review`, each holding the workspace-relative path of the document of that kind the current work uses, or `null` while the current work has none * `documents`: an object with the same keys, each listing every workspace-relative document of that kind in creation order, newest last, or an empty array before the first exists * `confirmed_decisions`: `null` when unavailable; otherwise an array of objects with string-or-null `decision`, `status`, and `evidence` * `blockers`: `null` when unavailable; otherwise an array of objects with string-or-null `id`, `summary`, and `resolution` * `next_action`: `null` or an object with string-or-null `phase` and `action` * `prioritized_follow_ups`: `null` when unavailable; otherwise an array of objects with integer `rank`, string-or-null `task`, `rationale`, and `evidence` Use empty arrays only for known-empty collections. Use `null` for unavailable values, report missing recovery-critical values as blockers, and never substitute placeholder identity or paths. When a phase skill returns a new document path, append it to that kind's `documents` list and set `artifact_paths` to it. When a later request in the session needs its own research or plan, name its work: a short lower-kebab-case name that describes the work and differs from the session's other document names, such as `task-board-polish`. Pass the name to the phase skills, which use it in place of `{{task_slug}}` for that work's research, plan, critique, changes, and review. Set `artifact_paths` to `null` for each kind the work has not produced yet, and keep a path only for an earlier document the work reuses, such as research its plan builds on. Earlier documents stay in `documents`, so the state, together with the documents' references to each other, ties the session's documents together. This illustrative state, at `.copilot-tracking/rpi-sessions/2026-10-20/report-export/report-export-csv-state.json`, belongs to a child loop in Implement; the field definitions govern. ```json { "task_id": "report-export-csv", "task_slug": "report-export-csv", "session_name": "Report export", "parent_task": { "task_id": "report-export", "task_slug": "report-export", "state_path": ".copilot-tracking/rpi-sessions/2026-10-20/report-export/report-export-state.json" }, "child_tasks": [], "mode": "automatic", "active_phase": "Implement", "status": "active", "session_status": "running", "artifact_paths": { "research": ".copilot-tracking/research/2026-10-21/report-export-csv-research.md", "plan": ".copilot-tracking/plans/2026-10-21/report-export-csv-plan.md", "critique": null, "changes": ".copilot-tracking/changes/2026-10-21/report-export-csv-changes.md", "review": null }, "documents": { "research": [".copilot-tracking/research/2026-10-21/report-export-csv-research.md"], "plan": [".copilot-tracking/plans/2026-10-21/report-export-csv-plan.md"], "critique": [], "changes": [".copilot-tracking/changes/2026-10-21/report-export-csv-changes.md"], "review": [] }, "confirmed_decisions": [ { "decision": "Automatic progression boundary", "status": "through-review", "evidence": "User request 2026-10-20" } ], "blockers": [], "next_action": { "phase": "Implement", "action": "Implement P01-T02" }, "prioritized_follow_ups": [] } ``` ### Session and participation decisions Store preferences and gate state in `confirmed_decisions` without adding schema fields: * `Automatic session scope`: status `current`; evidence identifies the originating request, root task/state pointer, approved write boundary, acceptance criteria, and exclusions. Inherit unchanged across children unless the user approves a scope change. Recover missing scope from matching canonical evidence before selecting work; otherwise record a blocker. * `Automatic progression boundary`: `through-review` or `before-implementation`, with user authorization as evidence. Default a missing boundary in an existing automatic session to `through-review` and persist it before progression. * `Research decision participation`, `Planning decision participation`, `Review decision participation`, and `Follow-up decision participation`: `agent-owned` or `user-retained`, with direction or default provenance. Persist missing automatic preferences as `agent-owned` before use. Phase participation alone does not retain follow-up selection. * `Subagent use`: `auto`, or the user's direction on how phases use subagents, such as `none`, only named uses, or a direction for named phases. Persist explicit user direction and honor later explicit changes. * `Research lane effort` and `Review lane effort`: `auto`, or the level the user sets for every helper lane in that phase or for lanes identified by kind or topic. Persist explicit user direction and honor later explicit changes. * `Planning critique`: `standard`, `deep`, or `skip`. The session's first task uses the phase skill's default or explicit user direction; a child loop uses `skip` unless the user asked for a critique of follow-up work. Persist the setting before drafting and honor later explicit changes. When the user sets a critique reasoning effort, for every lens or for named lenses, record it in the same evidence. * `Review step`: `run` or `skip`. The session's first task defaults to `run`; a child loop defaults to `skip` unless the user asked for a Review of follow-up work. Persist explicit user direction and honor later explicit changes. * `Canvas`: status `current`; evidence names the canvas instance, handle, and host-reported provider `extensionId` that shows the session (see Canvas). ### Critique and Review records * Track the plan critique and Review through `active_phase`, `next_action`, and `artifact_paths`; the `Planning critique` and `Review step` decisions record a skipped step and its provenance. Record a critique or review path in `artifact_paths` before its record is first written, so the canvas and other readers follow the record as it grows. `rpi-plan` owns critique status and findings, and `rpi-review` owns its record and decisions; do not duplicate their payloads in state. * Mirror only derived active routing in `next_action` and accepted follow-up work in `prioritized_follow_ups`. When a Review record exists, read its Parent Decision Record before rebuilding stale projections and use its latest participation event. ### Transition persistence Before every state transition, including a mode change, Stop, child-loop change, and each Research, Plan, Implement, Review, or Follow-up movement: 1. Immediately persist the current state with `next_action` set to the intended destination and action. Do not perform the transition if this write fails. 2. Perform the transition, then immediately persist the resulting `mode`, `active_phase`, task and parent identity when applicable, `session_status`, task `status`, and following `next_action`. If the resulting-state write fails, stop before starting destination work or taking another transition. Report the persistence blocker without claiming the transition was durably recorded. On recovery, reconcile the saved intent with canonical artifacts and any recorded child identity, persist the recovered state, and continue only after that write succeeds. Do not replay a phase activation or create a replacement child merely because the final state write is missing. ## Stop rules * In manual mode, do not infer phase advancement from apparent completion. Continue the active phase until the user explicitly requests the next phase or invokes its canonical skill. * Honor `before-implementation` before any automatic transition to Implement, including recovery with a pending Implement `next_action`. Complete applicable Plan gates, then use the state transition protocol to set `mode` to `manual`, `session_status` to `stopped`, `active_phase` to `Plan`, and task `status` to `active`. Set `next_action` to await an explicit `/rpi-implement` request. Do not activate Implement or mark the task completed. A generic resume does not authorize Implementation. * At the stop before Implementation, present the research and plan links and explain approach, trade-offs, open questions and readiness. Offer refinement, staying paused or explicitly starting eligible Implementation. Iteration preserves identity and boundaries; plan revisions and any follow-up critique follow `rpi-plan`. * Automatic progression does not require routine phase-start, phase-advancement, or plan-approval prompts. Retained material decisions use the phase skill's walkthrough without switching the session to manual mode. An unresolved evidence gap remains a blocker, not a request for the user to invent facts. * Request exceptional confirmation before a concrete destructive, hard-to-reverse, shared-system, or externally visible action when repository or platform safety rules require it. If confirmation is unavailable or declined, record a blocker and stop the affected action or phase. Automatic authorization is not consent for these actions. * Leave required human-review checkboxes unchecked and treat incomplete human review as a blocker or next action rather than completed approval. Human review is required only when an applicable instruction, domain artifact, or explicit user requirement names it for the affected action; an ordinary plan, an agent self-check, or a critique interruption does not create it. * Stop the affected phase when its gates, required evidence, decisions, or dependencies remain unresolved. If state and canonical artifacts cannot be reconciled, report each unavailable recovery-critical field and the next action without inventing identity, mode, or paths or restarting Research. * A completed task does not return to Implement, or to Review unless the user explicitly asks for a new review; remaining work continues in a child task, which cannot bypass missing evidence or unresolved required findings. * Task completion alone does not stop an automatic session. Continue eligible required work through Follow-up until session acceptance is established. Honor explicit Stop, manual mode, and the selected progression boundary; pauses for blockers or retained decisions do not claim completion. * If a proposed child repeats an unresolved finding without evidence of progress toward its resolution condition or a materially different evidence-backed corrective approach, record a no-progress blocker and the evidence or decision needed to resume. File changes or a new task identity alone do not demonstrate progress. Do not create another child merely to repeat a failed assessment. * Do not widen scope for optional cleanup or unrelated review suggestions. Report them as optional, unselected follow-ups; they do not prevent completion. An unresolved required finding cannot be relabeled optional to end the session. ## Flow ### Intake and recovery 1. Derive a candidate `task_id` and lower-kebab-case `task_slug` before loading state. Explicit issue or PR anchors, IDs, slugs, artifact paths, or task descriptions outrank ambient terminal history, recency, and state-file count. Same-task compaction or a confirmed running continuation retains identity; a new conversation alone does not imply resume. 2. Match that identity against state identity or recorded evidence in `.copilot-tracking/rpi-sessions/*/*/*-state.json`, then load and reconcile only the matching state. When none matches but the task's state file exists elsewhere under `.copilot-tracking`, move it into its session folder, add `session_name` and its links, and update the `state_path` that its parent's `child_tasks` and its children's `parent_task` give for it before continuing; record a blocker when a link cannot be reconciled. When a conversation starts or resumes a session and the host offers a chat rename tool, name the chat with `session_name` once; never rename it afterward or over a title the user chose. An unmatched explicit anchor starts a new task at the requested phase when prerequisites exist, otherwise Research. An ambiguous explicit resume stops before state creation or mutation and asks for the smallest identity clarification. 3. Resolve mode using Mode choice. Continue matching state from its recorded mode, active phase, next action, task status, session status, and canonical evidence. Check a pending Implement transition against `before-implementation` before activating the phase. Do not restart Research on resume or automatic entry. 4. Keep state current at material decisions, evidence changes, blockers, handoff, compaction, and closeout. Apply Transition persistence for every movement. Reconcile and rank follow-ups after material evidence changes in any phase. ### Phase activation Read and activate the matching skill when its phase becomes eligible, including the references that skill requires. Pass task identity, current decisions, blockers, evidence and finding IDs, scope, and canonical state/artifact pointers; exclude raw helper returns and obsolete artifact bodies. The skill owns its artifact construction, phase-local decisions, validation, gates, and any optional helper use; no phase requires a subagent. Pass the persisted `Subagent use` to every phase skill, which uses subagents only when a dispatch tool is available and that direction allows them, and runs independent subagent work in parallel. When a phase skill selects a subagent's effort per dispatch, as `rpi-research` and `rpi-review` do for each helper lane and `rpi-plan-critique` does for each `RPI Plan Critic` lens and its general-purpose fallback, use the skill's values. Otherwise default an optional subagent to `Claude Haiku 5.5 (copilot)` at `max` reasoning effort: a custom subagent keeps the `model:` and `reasoning-effort:` its frontmatter declares, as `RPI Researcher` and `RPI Reviewer` declare these defaults, and otherwise inherits the parent's settings, and a general-purpose subagent gets the default model and `reasoning_effort: max` when the dispatch tool accepts them. Outside a phase skill's per-dispatch selection, pass a different model, or an effort other than these, only when the user names one. 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`. The `rpi` session (including `RPI Agent` when preloaded) remains the parent and consumes the skill's return to decide session progression. For Research, Plan, and Review, pass `user-owned` participation in manual mode or the persisted automatic preference. Supply mode and provenance. Retained decisions pause only their material decision checkpoints; agent-owned decisions follow the skill's evidence-based protocol. * Research: activate `rpi-research` with any user-set `Research lane effort` when investigation is needed; otherwise record evidence-backed `reused` or `satisfied-and-skipped`. Record disposition and Planning Readiness or adequacy evidence in state decision evidence and the primary artifact when present. Advance only through the skill's continuation contract with applicable gates satisfied. * Plan: activate `rpi-plan` with persisted Planning participation, the `Planning critique` setting and any user-set critique reasoning effort, and existing plan and critique evidence. Consume its plan, critique disposition, decisions, and readiness. Apply `before-implementation` after Plan gates pass; otherwise Implement becomes eligible. * Implement: activate `rpi-implement` with the approved plan and declared scope. Consume its changes, current plan state, completed and remaining work, validation, blockers, follow-ups, and Review readiness. Bounded implementation completion alone does not establish full-task completion. * Review: when `Review step` is `skip`, record the skip and continue without activating `rpi-review`. Otherwise activate it with the reconciled artifact set, requested scope, `Review decision participation`, and any user-set `Review lane effort`. Use its depth default unless explicitly overridden by the user. As its primary parent, own final outcome and route decisions under its contract, then consume the canonical record for continuation rather than repeating the assessment. Manual mode remains in its current phase until explicit advancement. Automatic mode moves through each eligible remaining phase without ending the turn at an agent-owned transition. After Review, or after Implement when Review is skipped, manual mode presents the exact eligible commands and waits. Automatic mode transitions to Follow-up with task `status` `completed` for final Review execution `Complete` or, when Review was skipped, for completed full-plan implementation; otherwise `blocked`. Set `session_status` to `running` and `next_action` to follow-up assessment. Task completion records loop execution, not session acceptance. ### Follow-up assessment 1. Reconcile the current Review, or the changes record, validation, and plan follow-up items when Review was skipped, with inherited unresolved work, blockers, and acceptance criteria against `Automatic session scope`. Prune resolved or invalidated entries, merge duplicates, and retain unresolved sibling work across child transitions. 2. Classify each follow-up's rationale as required in-scope, optional improvement, or out-of-scope, with evidence. Rank eligible required work by dependencies and acceptance impact, then ease of implementation. Do not deepen discovery merely to populate the list. 3. Check progress against prior child findings and evidence using Stop rules before selecting another loop. 4. When current validation and completed Review evidence, or implementation evidence when Review was skipped, support every session acceptance criterion, no required findings remain, and no completion blockers remain, record completion evidence in the Review's Parent Decision Record, or in session state when Review was skipped, and transition `session_status` to `stopped`. Do not request another choice. Evidence invalidated by a child's changes cannot establish completion; include affected checks in that child's plan and validation.