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**
   ```bash
   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:
   ```markdown
   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:
   ```markdown
   Task: Fix all coding guideline violations
   Agent: general-purpose
   Agent Config: .claude/agents/code-fixer.md
   Authority: Can modify files
   ```

5. **Review Changes**
   ```bash
   # 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**
   ```bash
   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**
   ```bash
   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**
   ```bash
   # 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):

```bash
#!/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:
```bash
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:**
```markdown
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:**
```markdown
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:**

```bash
# 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:**
   ```bash
   cat FIXES_APPLIED.md
   ```

2. **Check git diff:**
   ```bash
   git diff --stat
   git diff --color | less
   ```

3. **Run test suite:**
   ```bash
   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:**
```markdown
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
```bash
git add . && git commit -m "[Baseline] Pre-fixer checkpoint"
```

### Review Fixes
```bash
cat FIXES_APPLIED.md
git diff --stat
```

### Commit Fixes
```bash
git add . && git commit -m "[Fix] Description

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

### Rollback Fixes
```bash
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