review-fix

Imported from damaverick/wp-qa-skills (skills/review-fix/SKILL.md). Install upstream with npx skills add damaverick/wp-qa-skills --skill review-fix. Copyright stays with the author.

Review-Fix Loop

Orchestrate an automated review-fix cycle that iterates until your code is clean. Each iteration spawns fresh sub-agents with full 200k context windows, fixes quick-fix items automatically, and accumulates strategic items for user decision at the end.

When to Use This Skill

• Before creating a PR - Get comprehensive feedback AND automatic fixes
• After major refactoring - Ensure quality across multiple review cycles
• When you want hands-off improvement - Let the loop fix issues automatically
• For iterative polish - Run until no quick-fix items remain

Parameters

Architecture

ORCHESTRATOR (main session - manages state only)
|
+-- REVIEW PHASE (8 parallel sub-agents, each with fresh 200k context)
|   +-- premium-ux-designer
|   +-- product-strategy-advisor
|   +-- general-purpose
|   +-- system-architect
|   +-- code-refactorer
|   +-- code-refactorer
|   +-- Explore (reusable components)
|   +-- Explore (dead code)
|
+-- FIX PHASE (single sub-agent, fresh 200k context)
|   +-- General agent with fix prompt + file context
|
+-- STATE FILE (.review-fix/state.json)
    +-- Tracks iterations, strategic items, fixed items, commits

Workflow

Step 0: Initialize State

Create/update the state file at .review-fix/state.json:

{
  "iteration": 1,
  "maxIterations": 3,
  "baseCommit": "main",
  "strategicItems": [],
  "fixedItems": [],
  "commits": [],
  "status": "in_progress",
  "startedAt": "2025-01-18T10:00:00Z",
  "branchName": "feature/example"
}

Step 1: Extract Branch Context

# Get current branch name
BRANCH=$(git branch --show-current)

# Get base commit (from parameter or default to main)
BASE_COMMIT="${base_commit:-main}"

# Validate base commit exists
if ! git rev-parse "$BASE_COMMIT" >/dev/null 2>&1; then
  # Fallback to master if main doesn't exist and no custom base provided
  if [ "$BASE_COMMIT" = "main" ]; then
    BASE_COMMIT="master"
  fi
fi

# Get diff stats against base commit
git diff --stat "$BASE_COMMIT"..HEAD

# Get list of changed files
git diff --name-only "$BASE_COMMIT"..HEAD

# Get commit messages since base
git log --oneline "$BASE_COMMIT"..HEAD

# Get detailed diff for context
git diff "$BASE_COMMIT"..HEAD --no-color

Step 2: Spawn 8 Reviewer Sub-Agents IN PARALLEL

Use the Task tool to spawn all 8 reviewers simultaneously with run_in_background: true.

Each reviewer receives:

1. The branch context (diff, changed files, commits)
2. Their specific review focus
3. Instructions to return JSON findings

Reviewer Prompts

All reviewers must return findings in this format:

[{
  "severity": "critical|important|suggestion",
  "label": "blocking|important|nit|suggestion",
  "category": "designer|pm|qa|architect|developer|maintainability|reusable",
  "file": "path/to/file.tsx",
  "line": 123,
  "issue": "Brief description of the problem",
  "suggestion": "Specific fix or improvement",
  "type": "quick-fix|strategic"
}]

Severity Labels

• blocking - Must fix before merge
• important - Should fix, discuss if disagree
• nit - Nice to have, not blocking
• suggestion - Alternative approach to consider

MAX 10 findings per reviewer. Focus on high-impact issues only.

Persona 1: Frontend Designer

Sub-agent: premium-ux-designer

Review the following changed files for UI/UX quality:
{list of component/page files}

Look for:
- Missing hover/focus states
- Inconsistent spacing or typography
- Poor loading states
- Accessibility issues (ARIA, keyboard nav)
- Animation opportunities
- Visual hierarchy issues

Review against project CLAUDE.md conventions for UI patterns and components.

Mark items as "quick-fix" if they're CSS/styling changes.
Mark items as "strategic" if they require design decisions or major restructuring.

Return findings as JSON array. MAX 10 findings.

Persona 2: Product Manager

Sub-agent: product-strategy-advisor

Review the overall feature changes for product fit:
{summary of changes and commit messages}

Look for:
- Is this solving the right problem?
- Feature creep or over-engineering
- Missing user-facing documentation
- Edge cases that affect UX
- Should this be built differently?

Most PM feedback should be marked "strategic" as it involves direction.

Return findings as JSON array. MAX 10 findings.

Persona 3: QA Engineer

Sub-agent: general-purpose

Review test coverage for new functionality:
{list of changed files}

Look for:
- Missing unit/integration tests
- Untested edge cases
- Error handling gaps
- Regression risks

Testing Checklist:
- [ ] Happy path tested
- [ ] Edge cases covered (empty arrays, null values, boundaries)
- [ ] Error cases tested (network failures, invalid input)
- [ ] Test names are descriptive
- [ ] Tests are deterministic (no flaky tests)
- [ ] Tests are independent (no shared mutable state)

Mark missing tests as "quick-fix" with specific test case suggestions.
Mark architectural test changes as "strategic".

Return findings as JSON array. MAX 10 findings.

Persona 4: System Architect

Sub-agent: system-architect

Review the architectural impact of changes:
{list of changed files with focus on services, utils, migrations}

Look for:
- Wrong abstraction level
- Scalability concerns
- Pattern violations (review against project CLAUDE.md conventions)
- Database design issues
- Performance bottlenecks

Security Checklist (mark violations as blocking):
- [ ] User input validated and sanitized
- [ ] SQL queries use parameterization
- [ ] Authentication/authorization checked on protected routes
- [ ] Secrets not hardcoded (check for API keys, passwords)
- [ ] Error messages don't leak sensitive info
- [ ] File uploads restricted (size, type)
- [ ] CSRF protection for state-changing operations

Most architecture feedback should be "strategic".
Simple pattern fixes can be "quick-fix".
Security violations should be "quick-fix" with label "blocking".

Return findings as JSON array. MAX 10 findings.

Persona 5: Senior Developer

Sub-agent: code-refactorer

Review code for quality and correctness:
{list of all changed files}

Look for:
- Bugs and logic errors
- React hook issues (deps, memory leaks)
- TypeScript type safety
- Naming conventions per project CLAUDE.md
- Error handling patterns

Performance Checklist:
- [ ] No N+1 queries in database operations
- [ ] Database queries use proper indexes
- [ ] Large lists are paginated
- [ ] Expensive operations are cached or memoized
- [ ] No blocking I/O in hot paths
- [ ] No unnecessary re-renders in React components

Most code fixes should be "quick-fix".

Return findings as JSON array. MAX 10 findings.

Persona 6: Code Maintainability

Sub-agent: code-refactorer

Review code for maintainability:
{list of changed files}

Look for:
- Overly complex code
- Code duplication
- Inconsistent patterns
- Missing comments on complex logic
- Dead code

Mark simplifications as "quick-fix".
Mark major refactors as "strategic".

Return findings as JSON array. MAX 10 findings.

Persona 7: Reusable Components

Sub-agent: Explore

Research the codebase for reuse opportunities:
{list of new components/utilities}

Look for:
- Existing components that could be reused
- New components that should be extracted
- Duplicate logic across files
- Missing shared utilities

Mark simple extractions as "quick-fix".
Mark architectural component changes as "strategic".

Return findings as JSON array. MAX 10 findings.

Persona 8: Dead Code Hunter

Sub-agent: Explore

Scan the codebase for dead code patterns:
{list of new/modified files}

Look for:
- Exported functions never imported elsewhere
- Unused imports at top of files
- Variables declared but never read
- Orphan files (never imported)
- Commented-out code blocks
- Unreachable code paths
- Unused dependencies

Mark as "quick-fix" for:
- Unused imports
- Unused variables
- Small unused functions

Mark as "strategic" for:
- Large unused modules
- Potentially unused dependencies
- Architectural dead code

Return findings as JSON array. MAX 10 findings.

Step 3: Collect and Aggregate Results

After all agents complete:

1. Use TaskOutput to retrieve results from each agent
2. Parse JSON findings from each response
3. Handle errors - If an agent fails, log it and continue with others
4. Deduplicate - Remove similar findings across personas
5. Separate by type:
   • quick-fix items -> Generate fix prompt for this iteration
   • strategic items -> Append to state.strategicItems

Step 4: Check Exit Conditions

Exit the loop if ANY of these are true:

• No quick-fix items found in this iteration
• iteration >= maxIterations
• Critical build/test failure that blocks progress

Update state.json:

{
  "iteration": 2,
  "status": "in_progress|completed|blocked",
  "lastIterationFindings": {
    "quickFix": 12,
    "strategic": 3
  }
}

Step 5: Generate Fix Prompt

Create a comprehensive fix prompt for quick-fix items only:

# Code Review Fixes - Iteration {N}

You are fixing issues identified by automated code review. Work through each section systematically.

## Instructions
1. Read each issue carefully before making changes
2. Make the changes specified - do not expand scope
3. After all fixes, run the project's build and lint commands
4. Do NOT modify or implement strategic items

## Changed Files Context
{List files that will need changes}

---

## Section 1: Critical Issues

### Issue 1.1: {issue title}
**File:** {file}:{line}
**Problem:** {description}
**Fix:**

{specific code change}

{... more critical issues}

---

## Section 2: Important Issues

{... important issues with same format}

---

## Section 3: Suggestions

{... suggestion issues with same format}

---

## Verification
After completing all fixes, run the project's build and lint commands to verify.

Report any errors encountered.

Step 6: Fix Phase (Fresh Sub-Agent)

Spawn a single fix agent with:

• The fix prompt from Step 5
• run_in_background: false (wait for completion)
• Fresh 200k context window

Sub-agent: general-purpose (or appropriate fixer type)

{The fix prompt generated in Step 5}

After fixing all issues:
1. Run the project's build and lint commands
2. Report any failures
3. If successful, report completion

Step 7: Commit Changes (if auto-commit enabled)

If auto-commit: true and fixes were made:

git add -A
git commit -m "fix: address code review findings (iteration {N})

Co-Authored-By: Claude Code <noreply@anthropic.com>"

Update state.json with commit hash:

{
  "commits": ["abc1234", "def5678"]
}

Step 8: Loop or Complete

If more iterations needed:

• Increment state.iteration
• Go back to Step 1

If complete:

• Update state.status: "completed"
• Proceed to Strategic Items Review

Step 9: Strategic Items Review

After all iterations complete, present accumulated strategic items to the user.

Grouping Strategy

• Group related items (max 4 per AskUserQuestion)
• Present one question at a time if many items

Question Format

AskUserQuestion with options:
- "Add to backlog" - Creates a backlog item
- "Implement now" - Queues for immediate implementation
- "Ignore" - Mark as dismissed

Backlog File Template

For items marked "Add to backlog", create:

# {Issue Title}

**Status**: Backlog
**Priority**: {Medium|High based on severity}
**Added**: {today's date}
**Source**: Code review (review-fix iteration {N})

## Overview
{Brief description of the issue}

## Context
{File and line references}

## Suggested Approach
{The suggestion from the review}

## Future Considerations
{Any related strategic items}

State File Reference

Location: .review-fix/state.json

{
  "iteration": 1,
  "maxIterations": 3,
  "baseCommit": "main",
  "status": "in_progress",
  "startedAt": "2025-01-18T10:00:00Z",
  "branchName": "feature/example",
  "strategicItems": [
    {
      "severity": "important",
      "category": "architect",
      "file": "lib/services/auth.ts",
      "line": 45,
      "issue": "Authentication should use middleware pattern",
      "suggestion": "Refactor to use middleware for auth checks",
      "iteration": 1
    }
  ],
  "fixedItems": [
    {
      "issue": "Missing error boundary",
      "file": "components/Dashboard.tsx",
      "iteration": 1
    }
  ],
  "commits": [
    "abc1234"
  ],
  "iterationHistory": [
    {
      "iteration": 1,
      "quickFixCount": 8,
      "strategicCount": 2,
      "commitHash": "abc1234"
    }
  ]
}

Iteration Logs

Each iteration creates a log file:

Location: .review-fix/iteration-{N}.json

{
  "iteration": 1,
  "timestamp": "2025-01-18T10:05:00Z",
  "reviewers": {
    "designer": { "findings": 3, "quickFix": 2, "strategic": 1 },
    "pm": { "findings": 2, "quickFix": 0, "strategic": 2 },
    "qa": { "findings": 4, "quickFix": 4, "strategic": 0 },
    "architect": { "findings": 2, "quickFix": 0, "strategic": 2 },
    "developer": { "findings": 5, "quickFix": 5, "strategic": 0 },
    "maintainability": { "findings": 3, "quickFix": 2, "strategic": 1 },
    "reusable": { "findings": 1, "quickFix": 1, "strategic": 0 },
    "deadcode": { "findings": 2, "quickFix": 2, "strategic": 0 }
  },
  "totalFindings": 20,
  "quickFixItems": [],
  "strategicItems": [],
  "fixPrompt": "...",
  "fixResult": "success|failure",
  "buildResult": "pass|fail",
  "commitHash": "abc1234"
}

Execution Instructions

When this skill is invoked:

1. Parse Parameters

/review-fix                              # defaults: max-iterations=3, auto-commit=true, base-commit=main
/review-fix max-iterations=5             # 5 iterations max
/review-fix auto-commit=false            # don't auto-commit
/review-fix skip-strategic=true          # skip strategic questions
/review-fix base-commit=abc123           # compare against specific commit
/review-fix base-commit=HEAD~3           # compare last 3 commits
/review-fix base-commit=develop          # compare against develop branch

2. Initialize

• Create .review-fix/ directory if needed
• Initialize or load state.json
• Check if resuming a previous run

3. Run Loop

for iteration in 1..maxIterations:
  1. Extract branch context
  2. Spawn 8 reviewers IN PARALLEL (run_in_background: true)
  3. Wait for all reviewers (TaskOutput)
  4. Aggregate findings
  5. If no quick-fix items -> exit loop
  6. Generate fix prompt
  7. Spawn fix agent (run_in_background: false)
  8. Run build/lint
  9. Commit if auto-commit enabled
  10. Update state

4. Strategic Review

• Present accumulated strategic items
• Create backlog files as needed

5. Final Report

# Review-Fix Complete

## Summary
| Metric | Value |
|--------|-------|
| Iterations | 2 |
| Quick-fix items resolved | 15 |
| Strategic items accumulated | 4 |
| Commits created | 2 |

## Commits
- `abc1234` - fix: address code review findings (iteration 1)
- `def5678` - fix: address code review findings (iteration 2)

## Strategic Items Handled
- Added to backlog: 2
- Implemented now: 1
- Ignored: 1

## Files Modified
{list of files touched during fix phases}

Error Handling

Reviewer Agent Failure

• Log the failure
• Continue with results from other reviewers
• Note in iteration log

Fix Agent Failure

• Save fix prompt to .review-fix/failed-fix-prompt-{N}.md
• Increment iteration
• Try again with fresh context
• After 2 consecutive failures, exit and report to user

Build/Lint Failure

• Do NOT commit
• Spawn debug sub-agent to analyze failure
• Include failure context in next fix prompt
• If build keeps failing, exit loop and report

Max Iterations Reached

• Normal exit condition
• Report remaining quick-fix items (if any) to user
• Suggest manual review

Persona-to-SubAgent Mapping

Tips

1. Start with default settings - 3 iterations is usually enough
2. Review strategic items thoughtfully - They represent real decisions, not just code fixes
3. Check the iteration logs - Useful for understanding what was found and fixed
4. Use skip-strategic for quick runs - If you just want automated fixes
5. Run after major features - Gets your code clean before PR review
6. Add .review-fix/ to .gitignore - State files are temporary and should not be committed