claudetools/.claude/REVIEW_FIX_VERIFY_WORKFLOW.md

Review-Fix-Verify Workflow

Purpose: Automated code quality enforcement with autonomous fixing capabilities Status: Production-Ready (Validated 2026-01-17) Success Rate: 100% (38/38 violations fixed, 0 errors introduced)

---

Overview

This document defines the complete workflow for automated code review and fixing in the ClaudeTools project. It outlines when to use review-only mode vs auto-fix mode, and how to execute each effectively.

---

Two-Agent System

Agent 1: Code Review Agent (Read-Only)

Purpose: Comprehensive auditing and violation detection File: .claude/agents/code-review.md (if exists) or use general-purpose agent Use When:

• Initial codebase audit
• Quarterly code quality reviews
• Pre-release compliance checks
• Security audits
• Need detailed reporting without changes

Capabilities:

• Scans entire codebase
• Identifies violations against coding guidelines
• Generates comprehensive reports
• Provides recommendations
• Does NOT modify files

Output: Detailed report with findings, priorities, and recommendations

---

Agent 2: Code-Fixer Agent (Autonomous)

Purpose: Automated violation fixing with verification File: .claude/agents/code-fixer.md Use When:

• Known violations need fixing (after review)
• Immediate compliance enforcement needed
• Bulk code transformations (e.g., emoji removal)
• Style standardization

Capabilities:

• Scans for specific violation patterns
• Applies automated fixes
• Verifies syntax after each change
• Rolls back failed fixes
• Generates change report

Output: Modified files + FIXES_APPLIED.md report

---

Workflow Decision Tree

Start: Code Quality Task
│
├─ Need to understand violations?
│  └─ YES → Use Code Review Agent (Read-Only)
│     └─ Review report, decide on fixes
│        ├─ Auto-fixable violations found?
│        │  └─ YES → Continue to Code-Fixer Agent
│        └─ Manual fixes needed?
│           └─ Document and schedule manual work
│
└─ Know what needs fixing?
   └─ YES → Use Code-Fixer Agent (Auto-Fix)
      └─ Review FIXES_APPLIED.md
         ├─ All fixes verified?
         │  └─ YES → Commit changes
         └─ Failures occurred?
            └─ YES → Review failures, manual intervention

---

Complete Workflows

Workflow A: Full Audit (Review → Fix)

Use Case: New codebase, comprehensive quality check, or compliance audit

Steps:

1. Create Baseline Commit

   git add .
   git commit -m "[Baseline] Pre-review checkpoint"
   

2. Launch Review Agent

   User: "Run the code review agent to scan for all coding guideline violations"
   

   Agent command:

   Task: Review codebase against coding guidelines
   Agent: general-purpose
   Prompt: [Read-only review instructions]
   

3. Review Findings

   • Read generated report
   • Categorize violations:
     • Auto-fixable (emojis, whitespace, simple replacements)
     • Manual-fix (refactoring, architectural changes)
     • Documentation-needed (clarify standards)

4. Apply Auto-Fixes

   User: "Run the code-fixer agent to fix all auto-fixable violations"
   

   Agent command:

   Task: Fix all coding guideline violations
   Agent: general-purpose
   Agent Config: .claude/agents/code-fixer.md
   Authority: Can modify files
   

5. Review Changes

   # Review the fixes
   cat FIXES_APPLIED.md
   
   # Check git diff
   git diff --stat
   
   # Verify syntax (if not already done by agent)
   python -m pytest  # Run test suite
   

6. Commit Fixes

   git add .
   git commit -m "[Fix] Auto-fix coding guideline violations
   
   - Fixed N violations across M files
   - All changes verified by code-fixer agent
   - See FIXES_APPLIED.md for details
   
   Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
   

7. Address Manual Fixes

   • Create issues/tasks for violations requiring manual work
   • Schedule refactoring work
   • Update coding guidelines if needed

Timeline: ~5-10 minutes for review, ~2-5 minutes for auto-fixes

---

Workflow B: Quick Fix (Direct to Fixer)

Use Case: Known violation type (e.g., "remove all emojis"), immediate fix needed

Steps:

1. Create Baseline Commit

   git add .
   git commit -m "[Baseline] Pre-fixer checkpoint"
   

2. Launch Fixer Agent

   User: "Run the code-fixer agent to fix [specific violation type]"
   
   Example: "Run the code-fixer agent to remove all emojis from code files"
   

3. Review & Commit

   # Review changes
   cat FIXES_APPLIED.md
   git diff --stat
   
   # Commit
   git add .
   git commit -m "[Fix] [Description of fixes]
   
   Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
   

Timeline: ~2-5 minutes total

---

Workflow C: Continuous Enforcement (Pre-Commit Hook)

Use Case: Prevent violations from being committed

Setup:

Create .git/hooks/pre-commit (or use existing):

#!/bin/bash
# Pre-commit hook: Check for coding guideline violations

# Check for emojis in code files
if git diff --cached --name-only | grep -E '\.(py|sh|ps1)$' | xargs grep -l '[✓✗⚠[ERROR][OK][DOCS]]' 2>/dev/null; then
    echo "[ERROR] Emoji characters found in code files"
    echo "Code files must not contain emojis per CODING_GUIDELINES.md"
    echo "Use ASCII markers: [OK], [ERROR], [WARNING], [SUCCESS]"
    echo ""
    echo "Files with violations:"
    git diff --cached --name-only | grep -E '\.(py|sh|ps1)$' | xargs grep -l '[✓✗⚠[ERROR][OK][DOCS]]'
    exit 1
fi

# Check for hardcoded credentials patterns (basic check)
if git diff --cached | grep -iE '(password|api_key|secret).?=.?["\'][^"\']+["\']'; then
    echo "[WARNING] Possible hardcoded credentials detected"
    echo "Review changes carefully before committing"
    # Don't exit 1 - just warn, may be false positive
fi

exit 0

Make executable:

chmod +x .git/hooks/pre-commit

---

Agent Invocation Best Practices

1. Pre-Authorization Strategy

Problem: Agents get prompted "allow all edits" when modifying files

Solution: When launching autonomous fixer agents, be ready to:

• Select option 2: "Yes, allow all edits during this session (shift+tab)"
• This grants blanket permission for the session
• Agent runs without further prompts

Future Improvement:

• Add a parameter to Task tool: auto_approve_edits: true
• Would bypass the permission prompt entirely for trusted agents

2. Clear Task Specifications

Good Agent Prompt:

Task: Fix all emoji violations in Python and shell scripts

Scope:
- Include: *.py, *.sh, *.ps1 files
- Exclude: *.md files, venv/ directories

Replacements:
- ✓ → [OK]
- ✗ → [ERROR]
- ⚠ → [WARNING]

Verification: Run syntax checks after each fix
Rollback: If verification fails
Report: Generate FIXES_APPLIED.md

Bad Agent Prompt:

Task: Fix the code

(Too vague - agent won't know what to fix or how)

3. Git Workflow Integration

Always create baseline commit BEFORE running fixer agent:

# BEFORE launching agent
git add .
git commit -m "[Baseline] Pre-fixer checkpoint"

# THEN launch agent
# Agent makes changes

# AFTER agent completes
git add .
git commit -m "[Fix] Agent applied fixes"

Why:

• Separates "what was there" from "what changed"
• Easy to revert if needed: git reset --hard HEAD~1
• Clean history showing before/after

4. Verification Steps

After Auto-Fixes, Always:

1. Review the report:

   cat FIXES_APPLIED.md
   

2. Check git diff:

   git diff --stat
   git diff --color | less
   

3. Run test suite:

   pytest  # Python
   bash -n scripts/*.sh  # Shell scripts
   # Or whatever tests your project uses
   

4. Spot-check critical files:

   • Review changes to entry points (main.py, etc.)
   • Review changes to security-sensitive code (auth, crypto)
   • Review changes to configuration files

---

Agent Configuration Reference

Code Review Agent Configuration

File: Use general-purpose agent with specific prompt

Prompt Template:

You are a code reviewer agent. Review ALL code files against coding guidelines.

**Required Reading:**
1. .claude/CODING_GUIDELINES.md

**Scan for:**
1. Emoji violations (HIGH priority)
2. Hardcoded credentials (HIGH priority)
3. Naming convention violations (MEDIUM priority)
4. Missing documentation (LOW priority)

**Output:**
Generate report with:
- Violation count by type
- File locations with line numbers
- Priority levels
- Recommendations

**Constraints:**
- READ ONLY - do not modify files
- Generate comprehensive report
- Categorize by priority

---

Code-Fixer Agent Configuration

File: .claude/agents/code-fixer.md

Key Sections:

• Mission Statement
• Authority & Permissions
• Scanning Patterns
• Fix Workflow (Backup → Fix → Verify → Rollback)
• Verification Phase
• Reporting Phase

Critical Features:

• Automatic syntax verification after each fix
• Rollback on verification failure
• Comprehensive change logging
• Git-ready state on completion

---

Success Metrics

Track these metrics to measure workflow effectiveness:

Fix Success Rate

Success Rate = (Successful Fixes / Total Fixes Attempted) × 100%
Target: >95%

Time to Fix

Average Time = Total Time / Number of Violations Fixed
Target: <5 seconds per violation

Verification Pass Rate

Verification Rate = (Files Passing Verification / Files Modified) × 100%
Target: 100%

Manual Intervention Required

Manual Rate = (Violations Requiring Manual Fix / Total Violations) × 100%
Target: <10%

---

Example Session Logs

Session 1: Emoji Removal (2026-01-17)

Task: Remove all emoji violations from code files

Workflow: Quick Fix (Workflow B)

Results:

• Violations found: 38+
• Files modified: 20
• Auto-fix success rate: 100% (38/38)
• Verification pass rate: 100% (20/20)
• Manual fixes needed: 0
• Time to fix: ~3 minutes
• Commits: 2 (baseline + fixes)

Outcome: SUCCESS - All violations fixed, zero errors introduced

Key Learnings:

1. Pre-authorization prompt still required (one-time per session)
2. Syntax verification caught potential issues before commit
3. FIXES_APPLIED.md report essential for reviewing changes
4. Git baseline commit critical for safe rollback

---

Troubleshooting

Agent Gets Stuck or Fails

Symptom: Agent reports errors or doesn't complete

Solutions:

1. Check agent prompt clarity - is the task well-defined?
2. Verify file paths exist - agent can't fix non-existent files
3. Check permissions - agent needs write access to files
4. Review error messages - may indicate syntax issues in files
5. Try smaller scope - fix one file type at a time

Verification Failures

Symptom: Agent reports syntax verification failed

Solutions:

1. Check FIXES_APPLIED.md for which files failed
2. Review git diff for those specific files
3. Manually inspect the changes
4. Agent should have rolled back failed changes
5. May need manual fix for complex cases

Too Many False Positives

Symptom: Agent flags violations that aren't actually violations

Solutions:

1. Update coding guidelines to clarify rules
2. Update agent scanning patterns to be more specific
3. Add exclusion patterns for false positive cases
4. Use review agent first to verify violations before fixing

Changes Break Tests

Symptom: Test suite fails after agent applies fixes

Solutions:

1. Rollback: git reset --hard HEAD~1
2. Review FIXES_APPLIED.md to identify problematic changes
3. Re-run agent with narrower scope (exclude failing files)
4. Fix remaining files manually with test-driven approach

---

Future Enhancements

Planned Improvements

1. Pre-Authorization Parameter

   • Add auto_approve_edits: true to Task tool
   • Eliminate permission prompt for trusted agents
   • Track: Which agents are "trusted" for auto-approval

2. Continuous Integration

   • GitHub Action to run code-review agent on PRs
   • Auto-comment on PR with violation report
   • Block merge if high-priority violations found

3. Progressive Enhancement

   • Agent learns from manual fixes
   • Updates its own fix patterns
   • Suggests new rules for coding guidelines

4. Multi-Project Support

   • Template agents for common fix patterns
   • Shareable agent configurations
   • Cross-project violation tracking

Research Areas

1. LLM-Based Syntax Verification

   • Replace python -m py_compile with LLM verification
   • Potentially catch logical errors, not just syntax
   • More nuanced understanding of "valid" code

2. Predictive Violation Detection

   • Analyze commit patterns to predict future violations
   • Suggest proactive fixes before code is written
   • IDE integration for real-time suggestions

---

Quick Reference Commands

Launch Review Agent

User: "Run code review agent to scan for all coding violations"

Launch Fixer Agent

User: "Run code-fixer agent to fix all [violation type]"
Example: "Run code-fixer agent to fix all emoji violations"

Create Baseline Commit

git add . && git commit -m "[Baseline] Pre-fixer checkpoint"

Review Fixes

cat FIXES_APPLIED.md
git diff --stat

Commit Fixes

git add . && git commit -m "[Fix] Description

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

Rollback Fixes

git reset --hard HEAD~1  # Rollback to baseline

---

Summary

The Review-Fix-Verify workflow provides:

1. Automated Quality Enforcement - Violations caught and fixed automatically
2. Safety Through Verification - Syntax checks prevent broken code
3. Comprehensive Auditing - Detailed reports of all changes
4. Git Integration - Clean commit history with baseline + fixes
5. Scalability - Handles 1 violation or 1000 violations equally well

Key Success Factors:

• Clear agent prompts
• Well-defined coding guidelines
• Baseline commits before fixes
• Comprehensive verification
• Detailed change reports

When to Use:

• Review Agent: Audits, assessments, understanding violations
• Fixer Agent: Known violations, bulk transformations, immediate fixes
• Both: Complete workflow for comprehensive quality improvement

---

Document Version: 1.0 Last Updated: 2026-01-17 Status: Production-Ready Validated: 38/38 fixes successful, 0 errors introduced