Structured Rpi

Structured RPI (Research-Plan-Implement)

A 6-phase workflow that decomposes complex tasks into gated stages, each producing a markdown artifact the user approves before advancing.

Quick Start

Use structured RPI to refactor the authentication module.

The workflow walks through six phases sequentially. Each phase produces a concise markdown artifact. You must get user approval before moving to the next phase.

Phases

How It Works

1. Announce the phase — State which phase you're entering and what it produces 2. Do the work — Research, analyze, design, or implement as appropriate 3. Present the artifact — Output a markdown artifact with a clear heading 4. Gate — Ask the user to approve, request changes, or skip ahead 5. Advance — Only move to the next phase after explicit user approval

Phase Gate Format

After each artifact, present:

Phase N complete. Ready to proceed to Phase N+1 (Name)?
Options: [approve] [request changes] [skip to phase N+X] [abort]

Key Rules

• Always gate — Never advance without user approval
• Phase 5 uses the Plan tool — Create a structured plan, not just prose
• Artifacts are markdown — Clean, scannable, no JSON blobs
• Keep artifacts concise — Prefer bullet points and tables over walls of text
• Self-contained — This workflow runs in a single session, no delegation

When to Use

When to Skip Phases

• User already provided requirements — Skip Phase 1 (Questions)
• Small scope, well-understood — Skip Phase 2 (Research)
• Single obvious approach — Compress Phase 3 (Design) into Phase 4 (Outline)
• User says "just do it" — Jump to Phase 6 with a lightweight plan

References

• phase-details.md - Detailed phase descriptions, inputs/outputs, done criteria
• structured-outputs.md - Artifact templates for each phase
• exit-conditions.md - When to skip, go back, or exit the workflow

Exit Conditions

When to skip phases, go back, or exit the workflow entirely.

When to Skip Phases

When skipping, briefly state what you're skipping and why:

Skipping Phase 1 (Questions) — requirements are clear from your description.
Moving to Phase 2 (Research).

When to Go Back

Return to a previous phase when:

• New information invalidates a decision — e.g., research reveals a constraint that changes the design
• User changes requirements — re-enter at the earliest affected phase
• Implementation hits a wall — go back to Design (Phase 3) if the approach doesn't work

When going back, state what changed and which phase you're re-entering:

Returning to Phase 3 (Design) — the chosen approach won't work because X.

When the Workflow Doesn't Apply

Don't use Structured RPI for:

• Simple bug fixes — Known cause, known fix. Just do it.
• One-line changes — No phases needed.
• Pure questions — User asking "how does X work?" doesn't need a workflow.
• Exploratory tasks — "Look around and tell me what you find" is research, not RPI.
• Urgent hotfixes — Speed matters more than process.

When to Abort

Stop the workflow if:

• User says "stop" or "abort" or "never mind"
• The task turns out to be trivial mid-workflow
• Requirements change so fundamentally that restarting is better than continuing

When aborting, summarize what was learned so the context isn't lost:

Aborting workflow. Key findings so far:
- X depends on Y
- The main risk is Z

Compressing the Workflow

For medium-complexity tasks, compress phases:

• Phases 1+2 — Ask questions while researching (present findings + remaining questions together)
• Phases 3+4 — Present design and outline together when there's one clear approach
• Phases 5+6 — For small implementations, the plan can be "here's what I'll do" followed immediately by doing it (with user approval)

Phase Details

Detailed description of each phase in the Structured RPI workflow.

Phase 1: Questions

Goal: Surface unknowns before doing any work.

Inputs: User's initial request.

Process:

• Identify ambiguities in the request
• List assumptions that need confirmation
• Ask about constraints (performance, compatibility, timeline)
• Clarify scope boundaries — what's in and out

Artifact: Numbered list of clarifying questions, grouped by category.

Done when: User has answered all questions (or explicitly deferred them).

---

Phase 2: Research

Goal: Gather context from the codebase and relevant docs.

Inputs: User's request + answers from Phase 1.

Process:

• Read relevant source files and tests
• Trace call paths and dependencies
• Check for existing patterns that should be followed
• Note technical constraints or risks discovered

Artifact: Findings summary with sections:

• Current state — How things work now
• Dependencies — What touches or is touched by this code
• Patterns — Existing conventions to follow
• Risks — Potential issues or edge cases

Done when: You have enough context to propose design options.

---

Phase 3: Design Discussion

Goal: Explore approaches and agree on direction with the user.

Inputs: Research findings from Phase 2.

Process:

• Propose 2-3 design options (avoid a single "obvious" choice)
• For each option: describe approach, list pros/cons, note tradeoffs
• Make a recommendation with reasoning
• Invite user input on direction

Artifact: Options table or list with tradeoff analysis and a recommendation.

Done when: User has selected an approach (or approved the recommendation).

---

Phase 4: Structure Outline

Goal: Agree on the shape of the solution before writing detailed steps.

Inputs: Chosen design from Phase 3.

Process:

• List files to create, modify, or delete
• Outline new components, functions, or types
• Show the dependency/call graph if helpful
• Identify the order of changes

Artifact: Bulleted outline of:

• Files and their changes
• New abstractions and their responsibilities
• Interface contracts between components

Done when: User agrees on the structural shape.

---

Phase 5: Plan

Goal: Create a concrete, step-by-step implementation plan.

Inputs: Approved structure from Phase 4.

Process:

• Use the Plan tool to create a structured plan
• Break work into discrete, testable steps
• Include acceptance criteria for each step
• Note verification commands (tests, type checks, etc.)

Artifact: A Plan tool plan with ordered steps.

Done when: User approves the plan.

---

Phase 6: Implement

Goal: Execute the plan and verify the result.

Inputs: Approved plan from Phase 5.

Process:

• Follow the plan step by step
• Run tests and verification after each logical chunk
• Report progress at natural milestones
• Surface any deviations from the plan for user approval

Artifact: Working code changes + verification output (test results, type checks).

Done when: All plan steps completed and verified. User confirms the result.

Structured Outputs

Artifact templates for each phase handoff. Keep artifacts concise — these are checkpoints, not documentation.

Phase 1: Questions Artifact

## Phase 1: Clarifying Questions

### Scope
1. Should X include Y or is that separate?
2. Are we targeting only Z or also W?

### Constraints
3. Any performance requirements?
4. Backward compatibility needed?

### Context
5. Is there existing work on this I should know about?

Phase 2: Research Artifact

## Phase 2: Research Findings

### Current State
- `src/auth/middleware.ts` handles token validation (L45-80)
- Sessions stored in Redis via `SessionStore` class

### Dependencies
- `UserService` calls `middleware.validate()` on every request
- 3 test files cover the auth path

### Patterns
- Existing middleware follows the `(req, res, next)` pattern
- Error responses use `ApiError` class from `src/errors.ts`

### Risks
- `SessionStore` has no interface — tightly coupled to Redis
- No integration tests for token refresh flow

Phase 3: Design Discussion Artifact

## Phase 3: Design Options

### Option A: Extract Interface + Adapter
- **Approach**: Define `ISessionStore`, wrap Redis in adapter
- **Pros**: Clean separation, testable, swappable backends
- **Cons**: More files, indirection
- **Effort**: Medium

### Option B: Refactor In-Place
- **Approach**: Add methods to existing `SessionStore`, keep Redis direct
- **Pros**: Fewer changes, faster
- **Cons**: Still coupled, harder to test
- **Effort**: Low

### Recommendation
Option A — the interface pays for itself in testability.

Phase 4: Structure Outline Artifact

## Phase 4: Structure Outline

### New Files
- `src/auth/session-store.interface.ts` — `ISessionStore` interface
- `src/auth/redis-session-adapter.ts` — Redis implementation
- `tests/auth/mock-session-store.ts` — Test double

### Modified Files
- `src/auth/middleware.ts` — Accept `ISessionStore` via constructor
- `src/auth/index.ts` — Update exports and wiring

### Deleted Files
- None

### Change Order
1. Create interface
2. Create Redis adapter (wraps existing code)
3. Update middleware to use interface
4. Create test double
5. Update existing tests

Phase 5: Plan Artifact

Use the Plan tool. The plan should have concrete steps like:

Step 1: Create ISessionStore interface
- File: src/auth/session-store.interface.ts
- Methods: get(key), set(key, value, ttl), delete(key), exists(key)
- Verify: tsc --noEmit passes

Step 2: Create RedisSessionAdapter
- File: src/auth/redis-session-adapter.ts
- Implements ISessionStore, wraps existing Redis calls
- Verify: existing tests still pass (no behavior change)
...

Phase 6: Implement Artifact

No template — this is working code. Report:

## Phase 6: Implementation Complete

### Changes Made
- Created `src/auth/session-store.interface.ts` (new)
- Created `src/auth/redis-session-adapter.ts` (new)
- Modified `src/auth/middleware.ts` (dependency injection)

### Verification
- `npm test` — 47 passed, 0 failed
- `tsc --noEmit` — clean
- Manual smoke test of login flow — works