rpi-kit 1.4.0 → 2.0.0

package/commands/rpi/research.md

@@ -1,7 +1,7 @@
 ---
 name: rpi:research
-description: Run research phase on a feature. Parallel agent analysis produces RESEARCH.md with GO/NO-GO verdict. Supports tiers (--quick, --standard, --deep).
-argument-hint: "<feature-slug> [--quick|--standard|--deep] [--force]"
+description: Analyze feasibility with Atlas (codebase) and Scout (external). Nexus synthesizes.
+argument-hint: "<feature-name> [--force]"
 allowed-tools:
   - Read
   - Write
@@ -12,159 +12,217 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-<objective>
-Run parallel research agents on a feature's REQUEST.md, synthesize findings into RESEARCH.md with a GO/NO-GO verdict.
-</objective>
+# /rpi:research — Research Phase
 
-<process>
+Run Atlas (codebase analysis) and Scout (external research) in parallel. Nexus synthesizes their outputs into RESEARCH.md with a GO / GO with concerns / NO-GO verdict.
 
-## 1. Load config and parse arguments
+---
 
-Read `.rpi.yaml` for folder path and default tier. Also read `profile` and `models` keys.
-Parse `$ARGUMENTS`:
-- First argument: `{feature-slug}` (required)
-- Flags: `--quick`, `--standard`, `--deep` (override config tier)
-- Flag: `--force` (proceed even if previous research exists)
+## Step 1: Load config and validate
 
-## 1b. Resolve model
+1. Read `.rpi.yaml` for config. Apply defaults if missing:
+   - `specs_dir`: `rpi/specs`
+   - `solutions_dir`: `rpi/solutions`
+   - `context_file`: `rpi/context.md`
+2. Parse `$ARGUMENTS` to extract `{slug}` and optional `--force` flag.
+3. Validate `rpi/features/{slug}/REQUEST.md` exists. If not:
+   ```
+   Feature '{slug}' not found. Run /rpi:new {slug} to start.
+   ```
+   Stop.
 
-Resolve the model for the `research` phase following the Model Resolution Algorithm in the rpi-workflow skill. Store as `{resolved_model}`. If a model is resolved, output the status message before agent spawns.
+## Step 2: Check existing research
 
-## 2. Resolve feature path
+1. Check if `rpi/features/{slug}/research/RESEARCH.md` already exists.
+2. If it exists and `--force` was NOT passed:
+   - Ask the user: "RESEARCH.md already exists for '{slug}'. Overwrite? (yes/no)"
+   - If no: stop.
+3. If `--force` was passed or user confirms: proceed (will overwrite).
 
-Parse `{feature-slug}` from arguments.
+## Step 3: Gather context
 
-**Resolution order:**
-1. Check if `{folder}/{feature-slug}/` exists → type = "feature", path = `{folder}/{feature-slug}`
-2. If not, Glob `{folder}/*/changes/{feature-slug}/` → if found, type = "change", path = matched path, parent_path = parent directory
-3. If multiple matches in step 2 → AskUserQuestion listing all matches with full paths
-4. If no match → error: `Feature not found: {feature-slug}. Run /rpi:new {feature-slug} first.`
+1. Read `rpi/features/{slug}/REQUEST.md` — store as `$REQUEST`.
+2. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
+3. Scan `rpi/specs/` for any specs relevant to the feature described in REQUEST.md — store as `$RELEVANT_SPECS`.
+4. Scan `rpi/solutions/` for any past solutions relevant to this feature — store as `$RELEVANT_SOLUTIONS`.
 
-If `type == "change"`:
-- Set `parent_path` to the parent feature directory
-- Read parent artifacts for agent context:
-  - `{parent_path}/REQUEST.md`
-  - `{parent_path}/research/RESEARCH.md` (if exists)
-  - `{parent_path}/plan/PLAN.md` (if exists)
-  - `{parent_path}/plan/eng.md` (if exists)
+## Step 4: Launch Atlas and Scout in parallel
 
-Validate that `{path}/REQUEST.md` exists. If not, error.
+Use the Agent tool to launch both agents simultaneously.
 
-If `{path}/research/RESEARCH.md` already exists and `--force` not set, ask user:
-"Research already exists for this feature. Overwrite?"
+### Atlas (codebase analysis)
 
-## 3. Determine agent composition by tier
+Launch Atlas agent with this prompt:
 
-**--quick (2 agents):**
-- requirement-parser
-- explore-codebase
+```
+You are Atlas. Analyze the codebase for feature: {slug}
 
-**--standard (4 agents):**
-- requirement-parser
-- explore-codebase
-- product-manager
-- senior-engineer
+## Request
+{$REQUEST}
 
-**--deep (6 agents):**
-- requirement-parser
-- explore-codebase
-- product-manager
-- senior-engineer
-- cto-advisor
-- ux-designer (only if REQUEST.md suggests UI involvement)
+## Project Context
+{$CONTEXT}
 
-## 4. Launch research agents in parallel
+## Relevant Specs
+{$RELEVANT_SPECS}
 
-Use the Agent tool to launch ALL selected agents concurrently in a single message. If a model was resolved in Step 1b, include `model: "{resolved_model}"` in each Agent tool call.
+## Relevant Past Solutions
+{$RELEVANT_SOLUTIONS}
 
-Each agent receives this prompt:
+Your task:
+1. Analyze the codebase for patterns, conventions, and architecture relevant to this feature
+2. Check rpi/specs/ for existing specifications that overlap or relate
+3. Check rpi/solutions/ for past solutions that could be reused
+4. Identify files likely affected, patterns to follow, and risks
+5. Output using your standard format: [Atlas -- Codebase Analysis]
 ```
-You are the {role-name} agent for the RPI workflow.
 
-Read the following files before analysis:
-- {folder}/{feature-slug}/REQUEST.md
+### Scout (external research)
 
-Then analyze the feature from your role's perspective following the RPI agent guidelines.
+Launch Scout agent with this prompt:
 
-Your output format:
-## [{Your Role Title}]
+```
+You are Scout. Research technical feasibility for feature: {slug}
 
-### {Section Name}
-Verdict: GO | CONCERN | BLOCK
-{Findings with evidence — cite specific files, deps, patterns}
+## Request
+{$REQUEST}
 
-### {Next Section}
-...
+## Project Context
+{$CONTEXT}
 
-Estimated Complexity: S | M | L | XL
+## Relevant Past Solutions
+{$RELEVANT_SOLUTIONS}
 
-Follow your role-specific rules as defined in the rpi-agents skill.
+Your task:
+1. FIRST check rpi/solutions/ for relevant past solutions before any external research
+2. Research technical feasibility of the proposed approach
+3. Evaluate alternative libraries/tools with trade-off comparison
+4. Identify risks: breaking changes, security issues, maintenance status
+5. Find relevant benchmarks, examples, or case studies
+6. Output using your standard format: [Scout -- Technical Investigation]
 ```
 
-For explore-codebase agent, also instruct it to scan the project codebase for relevant files, patterns, and conventions.
+## Step 5: Wait for completion
 
-If `type == "change"`, append to each agent prompt:
+Wait for both Atlas and Scout agents to complete. Store their outputs:
+- `$ATLAS_OUTPUT` — Atlas's codebase analysis
+- `$SCOUT_OUTPUT` — Scout's technical investigation
 
-```
-## Parent Feature Context
-{contents of parent artifacts read in step 2}
+## Step 6: Detect disagreements
+
+Compare Atlas and Scout outputs for contradictions:
+- Atlas says feasible but Scout says risky (or vice versa)
+- Different recommendations on approach, libraries, or architecture
+- Conflicting risk assessments
+
+If disagreements are detected, launch Nexus for a mini-debate:
 
-This is a CHANGE to an existing feature. Focus on:
-- What's different from the parent implementation
-- Compatibility with existing code
-- Breaking changes to watch for
 ```
+You are Nexus. Atlas and Scout disagree on key points for feature: {slug}
+
+## Atlas Output
+{$ATLAS_OUTPUT}
 
-## 5. Synthesize into RESEARCH.md
+## Scout Output
+{$SCOUT_OUTPUT}
 
-After all agents complete, use the Agent tool to launch the doc-synthesizer agent. If a model was resolved, include `model: "{resolved_model}"` in the Agent tool call.
+Identify the specific disagreements. For each one:
+1. State what Atlas argues
+2. State what Scout argues
+3. Evaluate the evidence for each position
+4. Declare the stronger position with reasoning
 
-Prompt:
+Output as: [Nexus -- Debate Summary]
 ```
-You are the doc-synthesizer agent for the RPI workflow.
 
-Merge the following research outputs into a single RESEARCH.md:
+Store the debate result as `$DEBATE_OUTPUT`.
 
-{paste all agent outputs}
+## Step 7: Nexus synthesis
+
+Launch Nexus agent to produce the final RESEARCH.md:
 
-Follow the RPI agent guidelines for doc-synthesizer:
-1. Executive summary first: verdict, complexity, risk in 5 lines
-2. No contradictions left unresolved
-3. Preserve the strongest finding from each agent
-4. If NO-GO, alternatives section is mandatory
-5. Section order: Summary → Requirements → Product → Codebase → Technical → Strategic → Alternatives
 ```
+You are Nexus. Synthesize research for feature: {slug}
 
-## 6. Write RESEARCH.md
+## Request
+{$REQUEST}
 
-Write the synthesized output to `{folder}/{feature-slug}/research/RESEARCH.md`.
+## Atlas Output
+{$ATLAS_OUTPUT}
 
-## 7. Present verdict
+## Scout Output
+{$SCOUT_OUTPUT}
 
-Display the executive summary to the user.
+## Debate Results (if any)
+{$DEBATE_OUTPUT or "No disagreements detected."}
 
-If **GO**:
-```
-Verdict: GO
-Next: /rpi:plan {feature-slug}
+Produce a single RESEARCH.md with this structure:
+
+# Research: {Feature Title}
+
+## Summary
+5 lines: verdict, complexity, risk, recommendation, key finding.
+
+## Atlas Findings
+{Key findings from Atlas's codebase analysis — preserve strongest evidence}
+
+## Scout Findings
+{Key findings from Scout's technical investigation — preserve strongest evidence}
+
+## Consensus
+{Points where Atlas and Scout agree}
+
+## Resolved Disagreements
+{For each disagreement: what Atlas said, what Scout said, resolution with reasoning}
+(or "No disagreements detected.")
+
+## Risks and Mitigations
+{Combined risk assessment from both agents}
+
+## Relevant Solutions
+{Past solutions from rpi/solutions/ that apply — for knowledge reuse}
+(or "No relevant past solutions found.")
+
+## Open Questions
+{Unresolved items that need user input}
+
+## Verdict
+{GO | GO with concerns | NO-GO}
+Confidence: {HIGH | MEDIUM | LOW}
+
+Rules for verdict:
+- Any BLOCK finding = NO-GO
+- No BLOCK + 2 or more CONCERN findings = GO with concerns
+- Otherwise = GO
+- NO-GO requires an Alternatives section
 ```
 
-If **GO with concerns**:
+## Step 8: Write RESEARCH.md and populate delta baselines
+
+1. Ensure directory exists: `rpi/features/{slug}/research/`
+2. Write the Nexus output to `rpi/features/{slug}/research/RESEARCH.md`
+3. If Nexus identified relevant existing specs in `rpi/specs/`:
+   - Ensure `rpi/features/{slug}/delta/` directory structure exists (ADDED/, MODIFIED/, REMOVED/)
+   - Copy relevant spec baselines into `delta/MODIFIED/` so the plan phase has reference copies
+   - This gives Mestre (plan phase) the current state of specs that will be changed
+
+## Step 9: Output summary
+
 ```
-Verdict: GO with concerns
-{list concerns}
-Next: /rpi:plan {feature-slug}
+Research complete: rpi/features/{slug}/research/RESEARCH.md
+
+Verdict: {GO | GO with concerns | NO-GO}
+
+Next: /rpi {slug}
+Or explicitly: /rpi:plan {slug}
 ```
 
-If **NO-GO**:
+If NO-GO:
 ```
-Verdict: NO-GO
-{reasons}
+Research complete: rpi/features/{slug}/research/RESEARCH.md
 
-Alternatives:
-{suggested alternatives from research}
+Verdict: NO-GO
 
-Override: /rpi:plan {feature-slug} --force
+Review the RESEARCH.md for details and alternatives.
+To override: /rpi:plan {slug} --force
 ```
-
-</process>