5-phase-workflow 1.1.1 → 1.2.0

package/src/commands/5/review-code.md

@@ -1,50 +1,89 @@
 ---
 name: 5:review-code
-description: Reviews code changes using CodeRabbit CLI by delegating execution and parsing to review-processor agent. Handles user interaction and fix application in main context.
+description: Reviews code changes using Claude (built-in) or CodeRabbit CLI. Handles user interaction and fix application in main context.
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep, AskUserQuestion, Task, mcp__jetbrains__*
 model: sonnet
 context: fork
 user-invocable: true
 ---
 
-# Review Code with CodeRabbit (Phase 5)
+# Review Code (Phase 5)
 
 ## Overview
 
-This skill automates code review using the CodeRabbit CLI. It supports two workflows:
+This command automates code review using a configurable review tool. The review tool is set in `.claude/.5/config.json` (`reviewTool` field). Two tools are supported:
+
+- **Claude** (default) — Built-in, zero setup. A fresh-context agent reviews code blind with no knowledge of what was built.
+- **CodeRabbit** — External CLI tool. Requires installation and authentication.
+
+Both tools produce the same structured output format, so all downstream steps (presenting results, applying fixes, saving reports) work identically regardless of which tool is used.
 
 **Workflow A: Interactive Review** (default)
 1. Checks prerequisites in main context
 2. Asks user what to review
-3. Delegates CodeRabbit execution and output parsing to review-processor agent
+3. Delegates review execution and output parsing to a spawned agent
 4. Presents structured results and asks user for decisions
 5. Applies fixes based on user approval
 6. Reports results
 
 **Workflow B: File-Based Annotation** (user preference)
-1. Runs CodeRabbit and saves findings to `.5/{feature-name}/review-{timestamp}-findings.md`
+1. Runs review and saves findings to `.5/{feature-name}/review-{timestamp}-findings.md`
 2. User edits the file to mark which findings to fix ([FIX], [SKIP], [MANUAL])
 3. User runs `/review-code apply` to read annotations and apply marked fixes
 
-**Architecture:** `Command -> Agent -> CodeRabbit CLI`
+**Architecture:** `Command -> Agent -> Review Tool`
 - This command stays in the main context (user interaction, fix application)
-- review-processor agent runs CodeRabbit and categorizes findings (forked context)
+- Spawned agent runs the review and categorizes findings (forked context)
+
+## ⚠️ Scope Constraint
+
+**THIS COMMAND REVIEWS CODE AND APPLIES USER-APPROVED FIXES ONLY.**
+
+✅ Read config to determine review tool
+✅ Check prerequisites for the selected tool
+✅ Ask user what to review
+✅ Spawn review agent (Claude or CodeRabbit)
+✅ Present findings overview to user
+✅ Ask user which fixes to apply
+✅ Apply ONLY user-approved fixes
+✅ Verify changes (compile and test)
+✅ Save review report
+
+❌ Run the review tool directly (agent does this)
+❌ Parse review output directly (agent does this)
+❌ Apply fixes without user approval
+❌ Skip the overview step — user must see all findings first
+❌ Skip verification — always compile and test after fixes
+
+**ALWAYS GET USER CONSENT BEFORE APPLYING ANY FIXES.**
 
 ## Prerequisites
 
-**Required:**
+**Claude reviewer (default):**
+- Git repository with changes to review
+- No additional setup needed
+
+**CodeRabbit reviewer:**
 - CodeRabbit CLI installed (`coderabbit` command available)
 - User logged in to CodeRabbit (`coderabbit auth status` shows authenticated)
 - Git repository with changes to review
 
-**Installation:**
-If CodeRabbit is not installed, see: https://docs.coderabbit.ai/cli/installation
-
 ## Review Process
 
-### Step 1: Check Prerequisites
+### Step 1: Determine Review Tool and Check Prerequisites
 
-Check if CodeRabbit CLI is installed and user is authenticated:
+**1a. Read config:**
+```bash
+# Read review tool preference
+cat .claude/.5/config.json
+# Look for "reviewTool" field — values: "claude", "coderabbit", or "none"
+```
+
+If no config exists or `reviewTool` is not set, default to `"claude"`.
+
+If `reviewTool` is `"none"`, inform user that automated review is disabled and exit.
+
+**1b. If review tool is CodeRabbit, check prerequisites:**
 
 ```bash
 # Check if coderabbit command exists
@@ -54,10 +93,18 @@ which coderabbit
 coderabbit auth status
 ```
 
-**If not installed or not logged in:**
+**If CodeRabbit not installed or not logged in:**
 - Inform user: "CodeRabbit CLI is not installed or you're not logged in."
-- Provide installation/login instructions
-- Exit without reviewing
+- Provide installation guidance:
+  - macOS: `brew install --cask coderabbit`
+  - Other: `curl -fsSL https://cli.coderabbit.ai/install.sh | sh`
+  - Then: `coderabbit auth login`
+- Ask user (via AskUserQuestion): "Would you like to switch to Claude (built-in) for this review instead?"
+  - Options: "Yes, use Claude for this review (Recommended)", "No, I'll install CodeRabbit first"
+  - If yes: proceed with Claude as the review tool for this session
+  - If no: exit without reviewing
+
+**1c. If review tool is Claude:** no prerequisites to check — proceed directly.
 
 ### Step 2: Check for Special Modes
 
@@ -87,34 +134,149 @@ Ask the user what to review and how to present results using AskUserQuestion:
 1. **Interactive** (default) - Show findings and apply fixes immediately
 2. **Save to file** - Save findings to `.5/{feature-name}/` for later annotation
 
-### Step 4: Spawn review-processor Agent
+### Step 4: Spawn Review Agent
+
+Branch based on the review tool determined in Step 1.
+
+#### Step 4A: CodeRabbit Review Agent
 
-Read `.claude/agents/review-processor.md` for agent instructions, then spawn via Task tool:
+If the review tool is **CodeRabbit**, spawn:
 
 ```
 Task tool call:
   subagent_type: general-purpose
+  model: sonnet
   description: "Run CodeRabbit review"
   prompt: |
-    {Contents of review-processor.md}
+    Run CodeRabbit CLI and categorize findings.
+
+    ## Review Scope
+    Scope: {scope from Step 3}
+    Base Branch: {branch-name if scope is "branch"}
+    Files: [{file-paths if scope is "files"}]
+
+    ## Process
+
+    1. **Run CodeRabbit** based on scope:
+       - staged: `coderabbit review --plain`
+       - files: `coderabbit review --plain {file1} {file2}`
+       - branch: `coderabbit review --plain --base {base-branch}`
 
-    ---
+    2. **Parse output** - Extract file paths, line numbers, severity, descriptions, suggested fixes
 
-    ## Your Task
+    3. **Categorize each finding:**
+       - **Fixable**: Mechanical fixes (unused imports, null checks, formatting, typos)
+       - **Questions**: Clarifications needed (validation logic, trade-offs)
+       - **Manual**: Requires judgment (refactoring, architecture, security)
 
-    Review Scope: {scope from Step 3}
+    ## Output Format
+    Return:
+    ```
+    Status: success | failed
+    Error: {if failed}
+
+    Summary:
+      total: {N}, fixable: {N}, questions: {N}, manual: {N}
+
+    Fixable Issues:
+    - file: {path}, line: {N}, description: {what}, fix: {suggestion}
+
+    Questions:
+    - file: {path}, line: {N}, question: {what the reviewer asks}
+
+    Manual Review:
+    - file: {path}, line: {N}, description: {what}, severity: {level}
+
+    Raw Output:
+    {full review output}
+    ```
+
+    ## Rules
+    - DO NOT apply fixes (parent handles with user consent)
+    - DO NOT interact with user
+    - Include ALL findings - let parent decide what to apply
+```
+
+#### Step 4B: Claude Review Agent
+
+If the review tool is **Claude**, spawn:
+
+```
+Task tool call:
+  subagent_type: general-purpose
+  model: sonnet
+  description: "Run Claude code review"
+  prompt: |
+    You are a code reviewer. You have NO prior knowledge of what was built, why it was built,
+    or what the implementation plan was. You are reviewing this code blind, purely on its merits.
+
+    ## Review Scope
+    Scope: {scope from Step 3}
     Base Branch: {branch-name if scope is "branch"}
     Files: [{file-paths if scope is "files"}]
+
+    ## Process
+
+    1. **Get the diff** based on scope:
+       - staged: run `git diff --cached`
+       - unstaged: run `git diff`
+       - all: run `git diff HEAD`
+       - branch: run `git diff {base-branch}...HEAD`
+       - files: run `git diff -- {file1} {file2}` (or `git diff --cached -- {file1} {file2}` if staged)
+
+    2. **Read full files** — For every file that appears in the diff, read the complete file content.
+       Also read 1 level of imports (files directly imported by changed files) to understand context.
+
+    3. **Review for:**
+       - **Bugs**: Logic errors, off-by-one, null/undefined access, race conditions, missing error handling
+       - **Security**: Injection, XSS, auth bypass, secrets exposure, insecure defaults
+       - **Performance**: N+1 queries, unnecessary allocations, missing pagination, blocking operations
+       - **Code quality**: Dead code, unclear naming, duplicated logic, overly complex conditionals
+       - **API design**: Inconsistent interfaces, missing validation, breaking changes, poor error responses
+
+    4. **Categorize each finding:**
+       - **Fixable**: Mechanical fixes (unused imports, null checks, formatting, typos, dead code removal)
+       - **Questions**: Clarifications needed (validation logic, trade-offs, ambiguous intent)
+       - **Manual**: Requires judgment (refactoring, architecture decisions, security implications)
+
+    ## Output Format
+    Return:
+    ```
+    Status: success | failed
+    Error: {if failed}
+
+    Summary:
+      total: {N}, fixable: {N}, questions: {N}, manual: {N}
+
+    Fixable Issues:
+    - file: {path}, line: {N}, description: {what}, fix: {suggestion}
+
+    Questions:
+    - file: {path}, line: {N}, question: {what the reviewer asks}
+
+    Manual Review:
+    - file: {path}, line: {N}, description: {what}, severity: {level}
+
+    Raw Output:
+    {full review analysis}
+    ```
+
+    ## Rules
+    - DO NOT apply fixes (parent handles with user consent)
+    - DO NOT interact with user
+    - Include ALL findings - let parent decide what to apply
+    - Be thorough but practical — focus on real issues, not style nitpicks
+    - You have NO context about the feature intent — review what the code DOES, not what it was supposed to do
 ```
 
 ### Step 5: Process Agent Results
 
-Receive structured results from review-processor:
+Receive structured results from the agent:
 - Total issues count
 - Categorized findings: fixable, questions, manual
-- Raw CodeRabbit output
+- Raw review output
 
-If agent returned failure (CodeRabbit failed), report error and exit.
+If agent returned failure (review failed), report error and exit.
 
 ### Step 6: Branch Based on Review Mode
 
@@ -129,7 +291,7 @@ If agent returned failure (CodeRabbit failed), report error and exit.
 Present a concise overview of all findings:
 
 ```
-CodeRabbit Review Results:
+Code Review Results:
 
 Summary:
 - Total Issues: {N}
@@ -174,7 +336,7 @@ Only apply fixes that the user has agreed to:
 
 ### Step 9: Handle Questions Based on User Preference
 
-If there are questions from CodeRabbit, use AskUserQuestion:
+If there are questions from the reviewer, use AskUserQuestion:
 
 **Options:**
 1. "Ask me for each" - Present each question individually
@@ -215,45 +377,18 @@ After applying fixes:
 
 ### Step 9c: Generate Review Summary
 
-Create comprehensive summary report:
-
-```markdown
-# CodeRabbit Review Summary
-
-**Reviewed:** {scope}
-**Timestamp:** {timestamp in ISO 8601 format, e.g., 2026-01-28T10:30:45Z}
-**User Decisions:** {summary of user choices}
-
-## Summary
-
-- **Total Issues:** {N}
-- **Applied with User Approval:** {N}
-- **User-Resolved Questions:** {N}
-- **Manual Review Needed:** {N}
-- **Skipped by User:** {N}
-
-## Applied Fixes (User Approved)
-
-- `ProductFactory.ts:45` - Added null check for parameter
-- `OrderValidator.ts:23` - Removed unused import
+Create comprehensive summary report using the template structure.
 
-## User-Resolved Questions
+**Template Reference:** Use the structure from `.claude/templates/workflow/REVIEW-SUMMARY.md`
 
-- `ProductFactory.ts:67` - Added empty string validation (user answered: yes)
-
-## Manual Review Needed
-
-- `ProductFactory.ts:120` - Consider extracting this method (complexity: 15)
-
-## Skipped Issues
-
-- `ProductFactory.ts:200` - User chose not to apply
-
-## Files Modified
-
-- ProductFactory.ts (2 fixes applied)
-- OrderValidator.ts (1 fix applied)
-```
+The template contains placeholders for:
+- **Header:** Reviewed scope, timestamp, user decisions summary
+- **Summary:** Counts for total issues, applied fixes, user-resolved questions, manual review, skipped
+- **Applied Fixes:** List of fixes applied with user approval (file:line - description)
+- **User-Resolved Questions:** Questions answered by user with their decisions
+- **Manual Review Needed:** Issues requiring human judgment
+- **Skipped Issues:** Fixes user chose not to apply
+- **Files Modified:** Summary of modified files with fix counts
 
 ### Step 10: Save Findings to File (File-Based Mode)
 
@@ -282,72 +417,20 @@ Example: 20260128-103045
 
 **File format:**
 
-```markdown
-# Code Review Findings
-
-**Generated:** {timestamp in ISO 8601 format, e.g., 2026-01-28T10:30:45Z}
-**Scope:** {what was reviewed}
-**Total Findings:** {N}
-
----
-
-## How to Use This File
-
-1. Review each finding below
-2. For each finding, choose an action:
-   - `[FIX]` - Apply this fix automatically (leave as-is)
-   - `[SKIP]` - Don't apply this fix (change FIX to SKIP)
-   - `[MANUAL]` - Custom instructions (change FIX to MANUAL and add instructions)
-3. Save this file
-4. Run: `/review-code apply`
-
-The apply command will read your annotations and apply marked fixes.
-
----
-
-## Finding 1/{total}
-
-**File:** {file-path}
-**Line:** {line-number}
-**Category:** {Fixable|Question|Manual}
-**Severity:** {error|warning|suggestion}
-
-**Description:**
-{what CodeRabbit found}
-
-**Suggested Fix:**
-{how to fix it - can be multi-line}
-
-**Original CodeRabbit Message:**
-```
-{raw output from CodeRabbit}
-```
-
-**Action:** [FIX]
-
-**Custom Instructions:** (only if you selected [MANUAL])
-<!-- Add detailed instructions here if you want a custom fix -->
-
-
----
-
-## Finding 2/{total}
-
-...
-
----
-
-## Summary
-
-- Total: {N}
-- Fixable: {N}
-- Questions: {N}
-- Manual Review: {N}
-
-**Next Steps:**
-1. Edit this file to mark which findings to fix
-2. Run: `/review-code apply`
-```
+**Template Reference:** Use the structure from `.claude/templates/workflow/REVIEW-FINDINGS.md`
+
+The template contains:
+- **Header:** Generated timestamp, scope, total findings count
+- **How to Use This File:** Instructions for user annotation with [FIX], [SKIP], [MANUAL] actions
+- **Finding sections:** Repeated for each finding with:
+  - File path, line number, category, severity
+  - Description of what the reviewer found
+  - Suggested fix
+  - Original reviewer message
+  - Action placeholder (default [FIX])
+  - Custom instructions field for [MANUAL] fixes
+- **Summary:** Counts of total, fixable, questions, manual review
+- **Next Steps:** Instructions to edit and run `/review-code apply`
 
 **After saving file:**
 - Inform user: "Findings saved to .5/{feature-name}/review-{timestamp}-findings.md"
@@ -448,55 +531,6 @@ For interactive mode only, save the review summary to:
 .5/{feature-name}/review-{timestamp}.md
 ```
 
-## Instructions Summary
-
-### Interactive Mode (Default)
-1. **Check prerequisites** - CodeRabbit installed and logged in
-2. **Ask what to review** - Staged, unstaged, branch, or specific files
-3. **Ask review mode** - Interactive or save to file
-4. **Spawn review-processor** - Delegate CodeRabbit execution and parsing
-5. **Process results** - Receive categorized findings
-6. **Provide overview** - Show concise summary to user
-7. **Ask user** - Which fixes to apply, how to handle questions
-8. **Apply fixes** - Only user-approved fixes, using Edit tool
-9. **Handle questions** - Ask user for each if requested
-10. **Verify changes** - Compile and test after applying fixes
-11. **Save report** - Store in `.5/{feature-name}/`
-
-### File-Based Annotation Mode
-1. **Check prerequisites** - CodeRabbit installed and logged in
-2. **Ask what to review** - Staged, unstaged, branch, or specific files
-3. **User selects "Save to file"**
-4. **Spawn review-processor** - Delegate CodeRabbit execution and parsing
-5. **Process results** - Receive categorized findings
-6. **Save findings file** - Store structured findings in `.5/{feature-name}/review-{timestamp}-findings.md`
-7. **User edits file** - Mark findings as [FIX], [SKIP], or [MANUAL] with instructions
-8. **User runs `/review-code apply`** - Apply annotated fixes
-9. **Parse annotations** - Read user's action markers and custom instructions
-10. **Apply marked fixes** - Apply [FIX] and [MANUAL] fixes automatically
-11. **Verify changes** - Compile and test after applying fixes
-12. **Update findings file** - Append application results
-
-## Key Principles
-
-1. **Thin orchestrator** - Delegate CodeRabbit execution to agent, keep interaction in main context
-2. **User consent first** - Always get user approval before applying any fixes
-3. **Provide overview** - Give user a clear summary before asking for decisions
-4. **Transparency** - Report all actions taken and user decisions made
-5. **Verification** - Always compile and test after applying fixes
-6. **Non-intrusive** - If not installed or logged in, gracefully exit
-
-## DO NOT
-
-- DO NOT run CodeRabbit directly (agent handles this)
-- DO NOT parse CodeRabbit output directly (agent handles this)
-- DO NOT apply fixes without user approval
-- DO NOT auto-apply complex refactoring suggestions
-- DO NOT skip the overview step
-- DO NOT skip verification (compilation/tests)
-- DO NOT proceed if CodeRabbit is not installed
-- DO NOT assume user wants all fixes applied
-
 ## Error Handling
 
 ### CodeRabbit Not Installed
@@ -504,23 +538,37 @@ For interactive mode only, save the review summary to:
 CodeRabbit CLI is not installed.
 
 To install:
-1. Visit: https://docs.coderabbit.ai/cli/installation
-2. Follow installation instructions for your OS
-3. Run: coderabbit auth login
-4. Then re-run: /review-code
+- macOS: brew install --cask coderabbit
+- Other: curl -fsSL https://cli.coderabbit.ai/install.sh | sh
+- Then: coderabbit auth login
+
+Or switch to the built-in Claude reviewer by running /5:configure
+and selecting "Claude" as your review tool.
 ```
 
-### User Not Logged In
+### CodeRabbit User Not Logged In
 ```
 You're not logged in to CodeRabbit.
 
 To log in:
 1. Run: coderabbit auth login
 2. Follow authentication prompts
-3. Then re-run: /review-code
+3. Then re-run: /5:review-code
+```
+
+### Claude Review Agent Failed
+```
+Claude code review failed.
+
+Error: {error from agent}
+
+Troubleshooting:
+1. Check if git repository is valid
+2. Ensure there are changes to review (run git status)
+3. Try again — transient failures can occur
 ```
 
-### Agent Failed
+### CodeRabbit Agent Failed
 ```
 CodeRabbit review failed.
 
@@ -580,5 +628,4 @@ Action: Please review the suggested fix manually.
 
 ## Related Documentation
 
-- [Agent: review-processor](../agents/review-processor.md)
 - [Workflow Guide](../docs/workflow-guide.md)