rpi-research

rpi-research

Goal

Produce a dated, primary research artifact that gives the caller evidence, parent-owned decision state, and planning readiness without planning, implementing, or reviewing. Each executed research cycle completes wider, deeper, and contrarian waves in that order. The artifact, not the chat response, is the durable source of truth.

Use templates/research.md as the primary-artifact skeleton. Read references/research.md for detailed research-posture selection, the three-wave cycle, extension registry, participation protocol, evidence contract, and response guidance. Follow the shared conventions in copilot-tracking.instructions.md.

Derive {{task_slug}} from the primary target with lower-kebab-case and use the current date in YYYY-MM-DD. The default artifact path is .copilot-tracking/research/YYYY-MM-DD/{{task_slug}}-research.md. A caller-provided trusted sandbox or evidence root may mirror research/YYYY-MM-DD/{{task_slug}}-research.md; record the resolved root before writing.

Flow

1. Establish the research brief in the primary artifact: topic, purpose, audience or use, scope and non-goals, criteria, requested outputs, output mode, initial questions, research posture and its provenance, and any explicit limits or deadline. Infer an initial topic only when the conversation provides enough context, and label assumptions for verification.
2. Determine applicable extensions at intake.
   • Apply matching instruction files by applyTo glob to the research inputs and evidence path.
   • Identify domain skills whose descriptions match the topic or evidence need.
   • Identify research-specialist subagents by stable frontmatter name, routing description, and host visibility or registration.
   • Record every relevant instruction, skill, and specialist as selected or skipped with its provenance and scoped authority or output contract.
3. Resolve extensions in this order:
   1. Platform and host safety
   2. Explicit caller scope and criteria
   3. Matching repository instructions and enforced schemas
   4. This rpi-research contract
   5. Domain skills and specialists
   6. Examples and preferences Extensions may add scoped criteria or evidence. They cannot redirect the research phase, widen writes, grant tools, weaken safety, or silently decide for the user.
4. Use the native vscode_askQuestions tool for an optional intake checkpoint only when an answer about topic, scope, criteria, or priorities would materially change the research.
   1. Batch a small set of decision-relevant questions and prefer fixed options with a freeform choice where useful.
   2. Do not request secrets.
   3. When inputs are sufficient or interaction is unavailable, continue and record the no-interaction rationale.
5. Establish the current cycle before research action.
   1. Run the prior-knowledge gate, decompose answerable questions, classify independent uncertainties, and resolve a proportionate research posture from the brief and evidence.
      • expansive: apply no preset upper limit. Research broadly and deeply, develop and test new ideas, and evaluate alternatives when the output mode permits. Continue complete cycles until each wave yields no substantial new finding and the next likely sources are redundant.
      • balanced: investigate adjacent material beyond the immediate task when it could improve the answer, including new ideas and alternatives. Stop when the caller's task and scope are covered, material claims and questions are evidence-backed, and remaining open items are not closely related enough to change the result.
      • focused: investigate deeply within the caller's task and scope. Widen only when clear evidence shows that broader research could materially change the result; use native vscode_askQuestions and persist approval before crossing that boundary.
      • Prefer focused or balanced for a bounded internal task with named source targets and supplied failure evidence. Use expansive when the brief is broad, the decision space is materially unknown, or the caller or applicable codebase instructions select it.
   2. Record active caller direction controls, including additions, changes, narrowed scope, exclusions, discarded directions, selected posture and provenance, and explicit limits or deadline. When uncertainty would materially affect the research, use native vscode_askQuestions and persist the answer before continuing.
   3. Before substantive search or delegation, persist the canonical opening state in its owning sections, then send the opening update defined in Conversation guidance.
   4. Delegate only a named independent uncertainty whose isolated investigation materially improves evidence quality, parallelism, or context control. Keep tightly coupled or low-volume wave work inline. Use RPI Researcher as the default general worker for a delegated internal, external, or hybrid lane. Select a discovered specialist only when its routing description fits the uncertainty and its stable name, host visibility or registration, independent-lane fit, and output-contract fit support the dispatch.
   5. Pass each worker the cycle number, wave type, topic, one bounded lane, questions, criteria, scope, research posture, explicit limits, an exact caller-approved candidate lane path under the parent-approved research/subagents path or a mirrored trusted subagents path, and the distinct parent primary artifact path.
   6. Parallelize only independent lanes. When suitable dispatch is unavailable, investigate the focused lane inline and record the fallback.
6. Complete all three waves in order for each executed cycle. Do not stop the cycle after early evidence appears sufficient.
   1. Wider: investigate inline or dispatch named independent uncertainties to identify breadth for ideas, conjectures, hypotheses, claims, and questions, including relevant libraries, frameworks, APIs, schemas, contracts, standards, current resources, current decisions or documentation, and potential evidence.
   2. Deeper: parent-prioritize the material from Wider, then investigate inline or dispatch named independent uncertainties for key details, findings, evidence, examples, schemas, APIs, contracts, standards, patterns, practices, and relevant code or visual style.
   3. Contrarian: investigate inline or dispatch named independent uncertainties to seek credible counter-evidence and in-scope alternatives that challenge the active ideas, conjectures, hypotheses, claims, and questions. Honor caller exclusions and specific-only boundaries.
   4. Reflect after each material search or worker return as a separate action. Keep worker returns compact, lift evidence into the primary artifact rather than duplicating raw output, and apply the material-update decision rules in references/research.md.
7. Parent-synthesize the completed cycle. Map findings to questions and stable C# and W# evidence IDs. The parent alone records accepted, rejected, and deferred material with evidence-based rationale; workers provide evidence and synthesis pointers without selecting a final recommendation or decision state. Record alternatives, current and unresolved decisions, risks, potential further research, Planning Readiness, and Research disposition.
   • In convergence mode, select one recommendation only when the evidence supports it.
   • In analysis, audit, or comparison mode, record the decision state without selecting an implementation recommendation outside caller intent.
   • In research-only or no-handoff mode, record the evidence and explicit no-handoff reason.
   • The parent owns evidence-state classification and any user update. Workers provide evidence relationships without classifying evidence state or deciding whether a message is useful.
   • Use references/research.md to record whether the selected output mode supports planning and to determine continuation.
8. Evaluate whether another complete three-wave cycle is required under the selected posture. Repeat the full cycle when evidence is missing for material claims, conjectures remain unclear, hypotheses are untested or unresolved, required examples, APIs, schemas, contracts, or links are missing, or contrarian evidence weakens earlier material or introduces material questions. Do not impose a fixed cycle ceiling. When an explicit caller or codebase limit prevents a needed cycle, record the gap and readiness honestly.
9. After a completed cycle, use vscode_askQuestions only when a proposed direction, further-research choice, or material finding would significantly change the research. Persist answers, unanswered questions, resulting decisions, and selected further-research items before continuing.
10. When useful, offer a conversational walkthrough in the final response and use the primary artifact as its navigable source of truth. Reserve vscode_askQuestions for the material research decisions in steps 4, 5, and 9.