Plan Review Workflow

Plan Review Workflow

Philosophy: Context Over Convenience

The reviewer model only sees selected files—it's blind to the rest of the codebase. RepoPrompt's Context Builder (hereafter "Builder") is AI-powered—its strength is discovering related context the reviewer needs:

• Existing patterns the plan should follow
• Similar implementations for consistency
• Architectural context (how things connect)
• Dependencies and side effects

We already KNOW the plan file. Builder's job is finding the surrounding context that makes review meaningful.

Key insight: Builder produces a handoff prompt (factual, non-opinionated). We take that as foundation, then add our review criteria on top.

Phase 0: Window Selection

CRITICAL: Always start by listing windows and selecting the correct one.

rp-cli -e 'windows'

Output shows window IDs with workspace names. Identify the window for the project you're reviewing.

For all subsequent commands, use -w <id> to target that window:

rp-cli -w 1 -e 'tree --folders'

Tab Isolation (for parallel agents):

builder automatically creates an isolated compose tab with an AI-generated name. Subsequent commands in the same rp-cli invocation stay in that tab. For separate invocations, rebind by name or UUID:

# Builder output includes: Tab: <UUID> • <Name>
# Rebind in later commands:
rp-cli -w 1 -e 'workspace tab "<Name>" && select add file.md'

When possible, chain commands in single invocations to maintain tab context:

rp-cli -w W -e 'builder "..." && select add plan.md && select get'

Phase 1: Parse Arguments & Read the Plan

Resolve input first:

1. If file path exists → markdown plan
2. Else if matches Beads ID format or bd show <arg> succeeds → Beads issue
3. Else if bd search "<arg>" has unique match → use that issue
4. Else: ask user for clarification

Additional text in arguments = focus areas/context. Save these for Phase 3.

If Beads issue:

1. Fetch content: bd show <id> (text output is clean, includes children)
2. Save output for inclusion in chat prompt
3. Compose a concise summary of what the plan accomplishes (1-2 sentences for simple plans, more for complex epics)

If markdown plan:

Read the plan file (replace W with your window ID from Phase 0):

rp-cli -w W -e 'read <plan-file-from-args>'

Compose a concise but descriptive summary of what the plan accomplishes (for builder prompt). Simple plans: 1-2 sentences. Complex epics: brief paragraph capturing key scope.

Then search for supporting documentation:

# Find PRD if exists
rp-cli -w W -e 'search "PRD" --mode path'
rp-cli -w W -e 'search "prd_" --mode path'

# Find beads JSONL
rp-cli -w W -e 'search ".beads/" --mode path'

# Find architecture docs
rp-cli -w W -e 'search "architecture" --mode path'
rp-cli -w W -e 'search "docs/" --mode path'

Read any relevant supporting docs you find.

Phase 2: Context Discovery & Selection

Step 1: Run builder with intent (not details)

Give builder a simple, intent-focused prompt. Let it discover context autonomously:

rp-cli -w W -e 'builder "Review a plan to [CONCISE SUMMARY OF WHAT PLAN ACCOMPLISHES]"'

Examples:

• Simple: "Review a plan to add OAuth authentication to the API"
• Medium: "Review a plan to refactor the payment processing module to use the repository pattern and add retry logic"
• Complex: "Review a plan to rebuild the notification system with real-time WebSocket delivery, user preferences, batching, and multi-channel support (email, push, in-app)"

⚠️ DO NOT stuff the prompt with file lists, module names, or implementation details. Builder discovers those.

⚠️ WAIT: Builder takes 30s-5min. Do NOT proceed until it returns output. Do NOT send another builder command—just wait for the current one to complete.

Step 2: Capture builder's handoff prompt

Builder returns:

• File selection (what it discovered as relevant)
• Handoff prompt (factual summary of context)
• Open questions (ambiguities it identified)

Save the handoff prompt - this becomes the foundation for your review prompt.

Get the current prompt:

rp-cli -w W -e 'prompt get'

Step 3: Review and augment selection

Builder is AI-driven and non-deterministic. Review what it found, then add must-haves:

# Check what builder selected
rp-cli -w W -e 'select get'

# Always add the plan file (builder may not have selected it)
rp-cli -w W -e 'select add <plan-file>'

# Add supporting docs from Phase 1 (PRD, architecture, etc.)
rp-cli -w W -e 'select add <path-to-prd>'
rp-cli -w W -e 'select add <path-to-architecture-doc>'

# Add any files you know are critical that builder missed

Step 4: Verify final selection

rp-cli -w W -e 'select get'

Confirm selection includes:

• The plan file
• Supporting docs from Phase 1
• Related patterns/code builder discovered
• Anything else needed for thorough review

Why this matters: Chat only sees selected files. Missing context = incomplete review.

Phase 3: Carmack-Level Review

Step 1: Build the review prompt

Combine three pieces:

1. Builder's handoff prompt (from Phase 2 Step 2) - factual context foundation
2. Review criteria - Carmack-level checklist
3. User's focus areas (from arguments) - specific concerns to prioritize

Prompt structure:

[BUILDER'S HANDOFF PROMPT - paste as-is]

---

## Plan Under Review
[PASTE PLAN CONTENT - or for Beads, include `bd show` output]

## Review Focus
[USER'S FOCUS AREAS FROM ARGUMENTS, if any]

## Review Criteria

Conduct a John Carmack-level review. Evaluate against:

### 1. Simplicity & Minimalism
- Simplest possible solution?
- Unnecessary abstraction layers?
- YAGNI violations?

### 2. DRY & Code Reuse
- Duplicated logic?
- Reinventing existing utilities?
- Could leverage existing patterns?

### 3. Idiomatic Code
- Follows codebase patterns?
- Naming conventions consistent?

### 4. Architecture & Design
- Data flow makes sense?
- Clear boundaries/responsibilities?
- Circular dependencies?

### 5. Edge Cases & Error Handling
- Unhandled failure modes?
- Race conditions?

### 6. Testability
- Structure easily testable?
- Dependencies injectable?

### 7. Performance
- O(n²) or worse?
- Unnecessary allocations?

### 8. Security
- Injection vulnerabilities?
- Auth/authz gaps?

### 9. Maintainability
- Future devs will understand?
- Abstractions earning complexity?

## Output Format

For each issue:
1. **Severity**: Critical / Major / Minor / Nitpick
2. **Location**: Where in the plan
3. **Problem**: What's wrong
4. **Suggestion**: How to fix
5. **Rationale**: Why it matters

End with:
- Overall: Ship / Needs Work / Major Rethink
- Patterns from codebase the plan should adopt

**List ALL issues.** Agent fixes all Critical/Major/Minor before re-review.

Step 2: Execute review

Use chat in chat mode. The chat sees all selected files.

Initial review - MUST use raw call chat_send with "new_chat": true:

rp-cli -w W -e 'call chat_send {"message": "<COMBINED_PROMPT>", "mode": "chat", "new_chat": true, "chat_name": "Plan Review: [PLAN_NAME]"}'

⚠️ JSON escaping: Message must use \n for newlines, not literal line breaks.

⚠️ WAIT FOR RESPONSE: Chat takes 1-5+ minutes. Do NOT re-send or follow up until it returns.

Follow-up/re-review command - MUST use call chat_send with selected_paths to ensure files remain visible:

rp-cli -w W -e 'call chat_send {"message": "<FOLLOW_UP_MESSAGE>", "mode": "chat", "selected_paths": ["<FILE1>", "<FILE2>"]}'

⚠️ CRITICAL: Chat follow-ups do NOT automatically see the selection. You MUST pass selected_paths with the same files from your initial selection, or the reviewer loses file context.

Phase 3 Alternative: Export for External Review

If user chose export mode, skip the chat and export context instead.

Step 1: Set the review prompt

Build the combined prompt (same structure as Phase 3 Step 1), then set it:

rp-cli -w W -e 'prompt set "<COMBINED_PROMPT>"'

The prompt should include:

• Builder's handoff prompt (foundation)
• Plan content (or Beads issue summary)
• User's focus areas
• Review criteria checklist

Step 2: Export to file

rp-cli -w W -e 'prompt export ~/Desktop/plan-review-[PLAN_NAME].md'

This exports: file tree, codemaps, selected file contents, and the review prompt.

Step 3: Open for user

open ~/Desktop/plan-review-[PLAN_NAME].md

Step 4: Inform user

Tell the user:

Exported review context to ~/Desktop/plan-review-[PLAN_NAME].md

The file contains:
- Full file tree with selected files marked
- Code maps (signatures/structure)
- Complete file contents (plan + supporting docs)
- Review prompt with Carmack-level criteria

Paste into ChatGPT Pro, Claude web, or your preferred LLM.
After receiving feedback, return here to implement fixes.

Skip the Iteration and Fix loops — user handles those externally.

Iteration

Continue the chat to drill deeper if needed (remember to include selected_paths):

rp-cli -w W -e 'call chat_send {"message": "Elaborate on the [SPECIFIC CONCERN]. What exactly would you change?", "mode": "chat", "selected_paths": ["<FILE1>", "<FILE2>"]}'

Fix and Re-Review Loop

CRITICAL: After receiving review feedback, implement all fixes directly—edit the plan file or Beads issue, don't just document issues.

What MUST be fixed:

• Critical: Fix immediately, no exceptions
• Major: Fix immediately, no exceptions
• Minor: Fix immediately—these are real issues, not optional polish

What MAY be skipped:

• Nitpick: Optional style/preference items—fix if easy, skip if not

The Loop

1. Parse the review: Extract all issues by severity
2. Fix Critical → Major → Minor: Edit the plan to address each
   • For markdown plans: use Edit tool to update the file
   • For Beads issues: use bd update <id> --body "..."
3. Augment selection (if needed): Add any files touched during fixes that aren't already selected

   rp-cli -w W -e 'select add path/to/newly-relevant-file.ts'
   

4. Re-review: Continue the existing chat with detailed fix explanations

Re-review message template:

## Fixes Applied

### Critical fixes:
[If any - list with explanations]

### Major fixes:
1. [Issue name]: [What was wrong] → [What you changed] — [Why this approach]
2. ...

### Minor fixes:
1. [Issue name]: [Brief explanation of fix]
2. ...

## Plan Changes Summary
- [Section X] rewritten to [describe change]
- Added [new section/content] for [reason]
- Removed/simplified [what] because [why]

## Trade-offs Acknowledged
- [Any trade-offs or compromises made]

Please re-review.

Use raw JSON for multi-line messages - include selected_paths to maintain file context:

rp-cli -w W -e 'call chat_send {"message": "<RE_REVIEW_MESSAGE>", "mode": "chat", "selected_paths": ["<FILE1>", "<FILE2>"]}'

⚠️ JSON escaping: Use \n for newlines, \" for quotes inside the message string.

⚠️ CRITICAL: Always include selected_paths with the files from your initial selection. Without this, the reviewer cannot see file contents in follow-up messages.

5. Repeat: Continue until review passes (Ship)

Why skip builder on re-reviews? The chat already has full context from the initial review. Builder's job was discovery—that's done. Re-reviews verify fixes, not discover new context.

Why detailed re-review messages? The reviewer needs to understand:

• What concrete changes were made to the plan
• Why you chose that approach (trade-offs, patterns)
• How the plan evolved (not just "trust me, I fixed it")

When to skip a fix (rare—default is to fix):

• Reviewer lacked context (didn't see related docs, missed a constraint)
• Reviewer misunderstood the requirement or intent
• Suggested change would conflict with other plan sections
• Conflicts with established patterns or requirements

If skipping, explain WHY clearly in the re-review message so the reviewer can reconsider with full context.

Anti-pattern: Skipping Minor issues. "Minor" means "real issue, lower priority"—not "optional". Fix them.

Key Guidelines

Always use -w flag: Every rp-cli command (except windows) needs -w <id> to target the correct window. W = your window ID from Phase 0.

Token budget: Stay under ~160k tokens. Builder manages this, but verify with select get.

Chat sees only selection: Ensure the plan file, PRD, and relevant code are all selected before starting the review chat.

Anti-patterns to Avoid

• Stuffing builder prompt – don't list files/modules/details; give intent, let builder discover
• Ignoring builder's handoff prompt – it's the foundation; add criteria on top, don't replace
• Forgetting -w <id> flag – commands will fail with "Multiple windows" error
• Skipping builder – you'll miss architectural context
• Reviewing without PRD/beads context – you won't know the "why"
• Shallow review – thorough analysis takes time; don't rush
• Not selecting supporting docs – chat can't see what's not selected
• Documenting issues instead of fixing – after review feedback, edit the plan directly
• Skipping Minor issues – "Minor" ≠ "optional"; fix all Critical/Major/Minor before re-review