research-plan-implement

name	research-plan-implement
description	Three-phase RPI workflow (Research, Plan, Implement). Use for non-trivial code changes.

Research-Plan-Implement (RPI)

A disciplined three-phase workflow that trades speed for clarity, predictability, and correctness. Each phase has a validation gate that must pass before proceeding.

Core principle: Never let AI write code without first researching the codebase and producing a validated plan. A 1-page plan gives 10x leverage over reviewing 1,000 lines of AI code.

When to Use

• Non-trivial features, refactors, or bug fixes
• Unfamiliar or large codebases
• Tasks where incorrect code is costlier than slow code
• When previous direct-implementation attempts have failed

When NOT to Use

• Single-line fixes, typos, or trivial changes
• Tasks where you already have full context and a clear path
• Exploratory prototyping (use RPI when hardening the prototype)

Workflow

Copy this checklist and track progress:

- [ ] Phase 1: Research (FAR validated)
- [ ] Phase 2: Plan (FACTS validated)
- [ ] Phase 3: Implement (verified)

---

Phase 1: Research

Goal: Explore the codebase, find the right files. Make ZERO modifications.

Use sub-agents (Task tool with Explore type) to read broadly without polluting the main context. Sub-agents return only compressed facts.

Research Outputs

For each finding, record:

• File path and line number(s)
• What exists there (function signature, data structure, pattern)
• Why it matters to the current task

FAR Validation Gate

Every finding must pass all three:

Check	Question	Fail Example
Factual	Is this from actual code, not assumption?	"There's probably a config file somewhere"
Actionable	Does it include specific file path + line number?	"The auth module handles this"
Relevant	Is it directly related to the task?	Documenting unrelated utility functions

Template for research summary:

## Research Findings for: {task description}

### Finding 1: {short title}
- **File**: `src/auth/middleware.ts:42-67`
- **What**: `validateToken()` checks JWT expiry and role claims
- **Why**: We need to extend this to support API key auth

### Finding 2: {short title}
- **File**: `src/types/auth.ts:15-23`
- **What**: `AuthContext` interface defines `user`, `token`, `roles`
- **Why**: Must add `apiKey` field here

### FAR Check
- [x] All findings reference actual code with paths and line numbers
- [x] No assumptions or guesses included
- [x] Every finding directly relates to the task

Do NOT proceed to Phase 2 until FAR passes.

---

Phase 2: Plan

Goal: Produce a step-by-step plan where each step has code-level specificity.

A plan without code snippets is just a "feeling" -- it has no execution power.

Plan Structure

For each step:

### Step N: {action verb} + {what}

**File**: `path/to/file.ts:line-range`
**Change**: {precise description of what to add/modify/remove}
**Code sketch**:
  ```typescript
  // Before (current):
  function validateToken(token: string): AuthContext { ... }

  // After (planned):
  function validateAuth(credential: string | ApiKey): AuthContext { ... }

Verify: {how to confirm this step succeeded} Scope: Changes ONLY validateToken signature and body. Does NOT touch callers yet.

### FACTS Validation Gate

Every step must pass all five:

| Check | Question | Fail Example |
|-------|----------|-------------|
| **F**easible | Can this be done in the current environment? | "Migrate to a new framework" mid-task |
| **A**tomic | Does it do exactly one thing? | "Update auth and refactor tests" |
| **C**lear | Are file names, line numbers, and code snippets present? | "Update the relevant files" |
| **T**estable | Is there a concrete verification step? | "Make sure it works" |
| **S**coped | Is it clear what changes and what doesn't? | No mention of boundaries |

**FACTS checklist**:

```markdown
### FACTS Validation
- [ ] F: Every step is achievable in current environment
- [ ] A: Each step has exactly one objective
- [ ] C: Every step has file path, line numbers, and code sketch
- [ ] T: Every step has a specific verification command or check
- [ ] S: Every step states what it changes AND what it leaves untouched

Do NOT proceed to Phase 3 until FACTS passes.

Present Plan to User

After FACTS validation, present the plan for human review. The plan is the primary review artifact -- it's far more efficient to review a plan than to review generated code.

---

Phase 3: Implement

Goal: Execute the validated plan with minimal context pressure.

Execution Rules

1. Follow the plan step by step -- do not improvise or "improve" beyond scope
2. One step at a time -- complete and verify each step before the next
3. Use sub-agents for independent steps -- keep main context lean
4. Verify after each step -- run the verification defined in the plan

After Each Step

Step N: {title}
- Status: DONE / BLOCKED / MODIFIED
- Verification: {result of the verification step}
- Deviation: {none, or explain why plan was adjusted}

If a Step Fails

1. Do NOT retry blindly -- diagnose why it failed
2. Update the plan with new information
3. Re-validate FACTS on the updated step
4. If 3+ steps fail consecutively, STOP -- see Escalation below

---

Intent Compression

When the conversation becomes long or starts going off track (roughly 20+ turns):

1. Stop all implementation work
2. Summarize key research findings and plan state into a compressed format:

## Compressed Context for: {task}

### Validated Facts
- {fact 1 with file path and line number}
- {fact 2 with file path and line number}

### Plan Status
- Steps completed: {list}
- Current step: {N} - {status}
- Remaining: {list}

### Blockers
- {any unresolved issues}

3. Start a new conversation with this compressed context

Better input produces better output. A fresh context with compressed facts outperforms a bloated context with noise.

---

Sub-Agent Strategy

Sub-agents are sharding tools, not personas. Use them to:

Task	Agent Type	Returns
Broad codebase reading	Explore	Compressed file/function map
Targeted search	Explore	Specific paths and line numbers
Independent implementation steps	Bash or general-purpose	Step completion status
Test execution	Bash	Pass/fail with output

Rules:

• Sub-agents do the heavy reading; main agent does the reasoning
• Sub-agents return compressed facts, not raw file contents
• Never let main context absorb entire files when a sub-agent can extract the relevant lines

---

Escalation

When RPI plans repeatedly fail (3+ consecutive step failures), this signals that the task complexity exceeds what AI can handle with current context.

Action: Stop. Return to the whiteboard. The human must re-think the approach and break the problem down differently before re-engaging AI.

Do not brute-force through repeated failures -- that wastes context and produces bad code.