tools-only 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:
- If file path exists → markdown plan
- Else if matches Beads ID format or
bd show <arg>succeeds → Beads issue - Else if
bd search "<arg>"has unique match → use that issue - Else: ask user for clarification
Additional text in arguments = focus areas/context. Save these for Phase 3.
If Beads issue:
- Fetch content:
bd show <id>(text output is clean, includes children) - Save output for inclusion in chat prompt
- 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:
- Builder's handoff prompt (from Phase 2 Step 2) - factual context foundation
- Review criteria - Carmack-level checklist
- 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
- Parse the review: Extract all issues by severity
- 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 "..."
- 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' - 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.
- 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