name	code-maintenance
description	Comprehensive daily codebase maintenance with multi-agent scanning, automatic fixing of easy issues, and validation. Scans for security vulnerabilities, code quality issues, missing tests, duplicate code, and architectural violations. Automatically fixes simple issues like console.logs and unused imports. Use when user says "maintain the codebase", "run maintenance", "clean up the code", "audit the codebase", "daily maintenance check", or "fix and validate code".
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, Task, TodoWrite

Code Maintenance - Multi-Agent Swarm with Auto-Fix & Validation

Overview

This skill orchestrates 13 specialized agents in a sophisticated pipeline with comprehensive safety controls:

Safety Checkpoint - Create git commit checkpoint (REQUIRED FIRST)
Scan codebase for issues (7 agents in parallel ⚡)
Consolidate findings and identify quick wins (1 agent)
Auto-fix easy issues (1 agent)
Validate changes don't break anything (3 agents in parallel ⚡)
Reconcile and update ISSUES.md (1 agent)
Post-Validation - Re-run tests & build, show diff (REQUIRED LAST)

Total execution time: 20-30 minutes Output: Updated ISSUES.md + Fixed code + Validation report + User approval Safety: Automatic rollback if tests/build fail, manual rollback option provided

13-Agent Architecture

🔍 Phase 2: Scanning Agents (PARALLEL)

🔷 Agent 1: Documentation Guardian

Purpose: Validates documentation accuracy Reference: agents/documentation-guardian.md Parallel: YES - Run with agents 2-6

🔷 Agent 2: Issue Tracker Curator

Purpose: Maintains ISSUES.md as single source of truth Reference: agents/issue-tracker-curator.md Parallel: YES - Run with agents 1, 3-6

🔷 Agent 3: Code Quality Sentinel

Purpose: Finds quality issues, test failures, duplicate code Reference: agents/code-quality-sentinel.md Parallel: YES - Run with agents 1-2, 4-6

🔷 Agent 4: Architecture Enforcer

Purpose: Validates architectural patterns Reference: agents/architecture-enforcer.md Parallel: YES - Run with agents 1-3, 5-6

🔷 Agent 5: Performance & Security Auditor

Purpose: Security vulnerabilities, performance issues Reference: agents/performance-security-auditor.md Parallel: YES - Run with agents 1-4, 6

🔷 Agent 6: Refactoring Specialist

Purpose: Identifies refactoring opportunities Reference: agents/refactoring-specialist.md Parallel: YES - Run with agents 1-5, 7

🔷 Agent 7: Error & Log Explosion Monitor

Purpose: Detects excessive/duplicative logging and error storms (Sentry/Axiom) Reference: agents/error-explosion-monitor.md Parallel: YES - Run with agents 1-6 Critical: Monitors production costs and system health

Checks:

Axiom log volume and patterns (last 15 min)
Sentry error frequency and types (last 24h)
Empty/malformed logs
Duplicative logging
Error storms and infinite loops

Philosophy: Logs should be robust but not excessive

✅ Always log: errors, warnings, poor performance, critical events
❌ Don't log: successful operations at high frequency, duplicates, empty logs

🎯 Phase 3: Integration

🔷 Agent 8: Integration Validator

Purpose: Consolidate findings, identify auto-fixable issues Reference: agents/integration-validator.md Parallel: NO - Wait for agents 1-7 to complete Output: Consolidated report + list of auto-fixable issues

🔧 Phase 4: Auto-Fix

🔷 Agent 9: Auto-Fixer

Purpose: Automatically fix safe, easy issues Reference: agents/auto-fixer.md Parallel: NO - Sequential fixes for safety Fixes:

Remove console.log/debug statements
Remove unused imports
Fix auto-fixable ESLint issues
Add missing simple return types
Remove trailing whitespace

✅ Phase 5: Validation Agents (PARALLEL)

🔷 Agent 10: Build & Type Validator

Purpose: Ensure TypeScript still compiles Reference: agents/build-type-validator.md Parallel: YES - Run with agents 11-12 Checks: tsc --noEmit, no new any types

🔷 Agent 11: Test Suite Validator

Purpose: Ensure tests still pass Reference: agents/test-suite-validator.md Parallel: YES - Run with agents 10, 12 Checks: npm test, no new failures

🔷 Agent 12: Lint & Format Validator

Purpose: Ensure code meets quality standards Reference: agents/lint-format-validator.md Parallel: YES - Run with agents 10-11 Checks: eslint, no new violations

📋 Phase 6: Final Reconciliation

🔷 Agent 13: Final Reconciliation

Purpose: Update ISSUES.md with results Reference: agents/final-reconciliation.md Parallel: NO - Wait for validation to complete Actions:

Mark auto-fixed issues as "Fixed"
Add validation results
Update effort estimates
Generate final summary

Execution Flow

Phase 0: Safety Checkpoint (REQUIRED - 30 seconds)

CRITICAL: Execute these commands BEFORE starting maintenance

# 1. Check if there are uncommitted changes
git status --porcelain

If OUTPUT is not empty:
  # User has uncommitted changes - create checkpoint
  git add .
  git commit -m "Pre-maintenance checkpoint - $(date)"

  Output to user: "✓ Created pre-maintenance checkpoint commit"
Else:
  # Working directory is clean
  Output to user: "✓ Working directory clean, proceeding with maintenance"

# 2. Record current commit for later comparison
CHECKPOINT_COMMIT=$(git rev-parse HEAD)
Store CHECKPOINT_COMMIT for Phase 7

Rationale: This ensures we can always rollback to exactly where we started.

Phase 1: Initialization (1-2 min)

1. Create comprehensive todo list tracking all 13 agents
2. Read current ISSUES.md to understand existing state
3. Check recent git commits for context (git log --since="7 days ago")
4. Identify recently changed files for focused analysis
5. Create backup branch: git branch maintenance-backup-$(date +%s)

Phase 2: Parallel Scanning (5-10 min)

CRITICAL: Run agents 1-7 in SINGLE message with MULTIPLE Task calls

// Example of correct parallel execution:
// Send ONE message with SEVEN Task tool calls

Task({
  description: 'Agent 1: Documentation Guardian',
  subagent_type: 'general-purpose',
  prompt: `You are Agent 1: Documentation Guardian.

  Read: .claude/skills/code-maintenance/agents/documentation-guardian.md
  Follow ALL instructions in that file.
  Return your findings in the specified JSON format.`,
});

Task({
  description: 'Agent 2: Issue Tracker Curator',
  subagent_type: 'general-purpose',
  prompt: `You are Agent 2: Issue Tracker Curator.

  Read: .claude/skills/code-maintenance/agents/issue-tracker-curator.md
  Follow ALL instructions in that file.
  Return your findings in the specified JSON format.`,
});

// ... Tasks 3-7 in same message

Task({
  description: 'Agent 7: Error & Log Explosion Monitor',
  subagent_type: 'general-purpose',
  prompt: `You are Agent 7: Error & Log Explosion Monitor.

  Read: .claude/skills/code-maintenance/agents/error-explosion-monitor.md
  Follow ALL instructions in that file.

  CRITICAL: Check Axiom and Sentry for log/error explosions.
  Remember: Logs should be ROBUST but NOT EXCESSIVE.

  Return your findings in the specified JSON format.`,
});

Wait for ALL 7 agents to complete before proceeding.

Each agent returns:

{
  "agentName": "...",
  "findings": [...],
  "summary": {...},
  "criticalActions": [...]
}

Phase 3: Integration & Prioritization (2-3 min)

Task({
  description: 'Agent 8: Integration Validator',
  subagent_type: 'general-purpose',
  prompt: `You are Agent 8: Integration Validator.

  Input: Reports from agents 1-7 (provided below)

  Read: .claude/skills/code-maintenance/agents/integration-validator.md
  Follow ALL instructions to:
  1. Consolidate findings
  2. Deduplicate issues
  3. Assign priorities
  4. Identify auto-fixable issues (P3 and safe P2)

  Return:
  - consolidatedFindings (all issues)
  - autoFixableIssues (safe to auto-fix)
  - summary

  Agent Reports:
  ${JSON.stringify(agentReports)}`,
});

Output: List of auto-fixable issues to pass to Agent 9

Phase 4: Auto-Fix Easy Issues (3-5 min)

Task({
  description: 'Agent 9: Auto-Fixer',
  subagent_type: 'general-purpose',
  prompt: `You are Agent 9: Auto-Fixer.

  Read: .claude/skills/code-maintenance/agents/auto-fixer.md

  Auto-fixable issues identified:
  ${JSON.stringify(autoFixableIssues)}

  INSTRUCTIONS:
  1. Fix ONE category at a time
  2. After each category, run git diff to verify changes
  3. Only fix P3 and explicitly marked safe P2 issues
  4. NEVER fix P0 or P1 (too risky)
  5. Return list of what was fixed

  Categories to fix:
  - Remove console.log statements
  - Remove unused imports
  - Fix ESLint auto-fixable issues
  - Add simple return types where obvious

  Return JSON:
  {
    "fixed": [{ "issue": "...", "location": "...", "changesMade": "..." }],
    "skipped": [{ "issue": "...", "reason": "..." }],
    "summary": { "totalFixed": N, "filesModified": N }
  }`,
});

Output: List of fixed issues and modified files

Phase 5: Parallel Validation (2-3 min)

CRITICAL: Run agents 10-12 in SINGLE message with THREE Task calls

// Send ONE message with THREE Task tool calls

Task({
  description: 'Agent 10: Build & Type Validator',
  subagent_type: 'general-purpose',
  prompt: `You are Agent 10: Build & Type Validator.

  Read: .claude/skills/code-maintenance/agents/build-type-validator.md

  Files modified by auto-fixer:
  ${JSON.stringify(modifiedFiles)}

  INSTRUCTIONS:
  1. Run: tsc --noEmit
  2. Check for TypeScript errors
  3. Verify no new 'any' types introduced
  4. Return validation results`,
});

Task({
  description: 'Agent 11: Test Suite Validator',
  subagent_type: 'general-purpose',
  prompt: `You are Agent 11: Test Suite Validator.

  Read: .claude/skills/code-maintenance/agents/test-suite-validator.md

  Files modified: ${JSON.stringify(modifiedFiles)}

  INSTRUCTIONS:
  1. Run test suite
  2. Compare results to baseline
  3. Identify new failures (if any)
  4. Return validation results`,
});

Task({
  description: 'Agent 12: Lint & Format Validator',
  subagent_type: 'general-purpose',
  prompt: `You are Agent 12: Lint & Format Validator.

  Read: .claude/skills/code-maintenance/agents/lint-format-validator.md

  Files modified: ${JSON.stringify(modifiedFiles)}

  INSTRUCTIONS:
  1. Run ESLint
  2. Check for new violations
  3. Verify code formatting
  4. Return validation results`,
});

Wait for ALL 3 validators to complete.

Each validator returns:

{
  "validatorName": "...",
  "status": "PASSED" | "FAILED",
  "errors": [...],
  "warnings": [...],
  "recommendations": [...]
}

Phase 6: Final Reconciliation (1-2 min)

Task({
  description: 'Agent 13: Final Reconciliation',
  subagent_type: 'general-purpose',
  prompt: `You are Agent 13: Final Reconciliation.

  Read: .claude/skills/code-maintenance/agents/final-reconciliation.md

  Inputs:
  - Consolidated findings from Agent 8
  - Auto-fix results from Agent 9
  - Validation results from Agents 10-12

  INSTRUCTIONS:
  1. Update ISSUES.md:
     - Mark auto-fixed issues as "Fixed"
     - Add validation results
     - Add remaining open issues
  2. If validation FAILED:
     - Revert auto-fixes: git reset --hard HEAD
     - Mark issues as "Auto-fix attempted but validation failed"
  3. Generate final summary

  Return final report`,
});

Phase 7: Post-Execution Validation (REQUIRED - 3-5 min)

CRITICAL: Execute these validation steps AFTER all agents complete

# 1. Show what changed since checkpoint
Bash: git diff ${CHECKPOINT_COMMIT} --stat
Bash: git diff ${CHECKPOINT_COMMIT} --name-only

Output to user:
"📊 Changes made during maintenance:
[list of modified files and stats]"

# 2. Re-run full test suite
Bash: npm test

If tests FAIL:
  Output: "❌ TESTS FAILED - Rolling back all changes"
  Bash: git reset --hard ${CHECKPOINT_COMMIT}
  Output: "✓ Rolled back to pre-maintenance state"
  ABORT with error report
Else:
  Output: "✅ All tests passed"

# 3. Re-run build
Bash: npm run build

If build FAILS:
  Output: "❌ BUILD FAILED - Rolling back all changes"
  Bash: git reset --hard ${CHECKPOINT_COMMIT}
  Output: "✓ Rolled back to pre-maintenance state"
  ABORT with error report
Else:
  Output: "✅ Build successful"

# 4. Final safety check - show full diff for user review
Bash: git diff ${CHECKPOINT_COMMIT}

Output to user:
"
═══════════════════════════════════════════════════════════════
✅ MAINTENANCE COMPLETE - VALIDATION PASSED
═══════════════════════════════════════════════════════════════

All changes validated successfully:
✅ Tests passed
✅ Build successful
✅ Code quality maintained

Review changes above. If you want to keep them:
  git add .
  git commit -m 'Apply code maintenance fixes'

If you want to REVERT everything:
  git reset --hard ${CHECKPOINT_COMMIT}

Backup branch available: maintenance-backup-[timestamp]
"

Phase 8: Final Report (1 min)

Display comprehensive summary to user.

Instructions for Claude

CRITICAL SAFETY PROTOCOL

MUST execute phases in this exact order:

Phase 0: Safety Checkpoint - REQUIRED FIRST
- Create git checkpoint commit if needed
- Record CHECKPOINT_COMMIT hash
- This enables rollback to exact starting point
Phase 7: Post-Execution Validation - REQUIRED LAST
- Show diff from checkpoint
- Re-run tests (rollback if fail)
- Re-run build (rollback if fail)
- Give user final approval/rollback options

CRITICAL PARALLEL EXECUTION RULES

MAXIMIZE PARALLELISM for faster execution:

Agents 1-7 MUST run in parallel ⚡

Send ONE message with SEVEN Task calls
Do NOT send 7 separate messages
Wait for ALL to complete before Phase 3
Example:

// CORRECT: One message with 7 parallel Task calls
(Task(agent1),
  Task(agent2),
  Task(agent3),
  Task(agent4),
  Task(agent5),
  Task(agent6),
  Task(agent7));

// WRONG: 7 separate messages
Task(agent1); // message 1
Task(agent2); // message 2 - DON'T DO THIS

Agents 10-12 MUST run in parallel ⚡
- Send ONE message with THREE Task calls
- Do NOT send 3 separate messages
- Wait for ALL to complete before Phase 6
- Example:
```
// CORRECT: One message with 3 parallel Task calls
(Task(agent10), Task(agent11), Task(agent12));
```
Sequential phases:
- Phase 0: Safety Checkpoint (FIRST)
- Phase 1: Initialization
- Phase 2: Agents 1-7 (PARALLEL)
- Phase 3: Agent 8 (wait for 1-7)
- Phase 4: Agent 9 (wait for 8)
- Phase 5: Agents 10-12 (wait for 9, then PARALLEL)
- Phase 6: Agent 13 (wait for 10-12)
- Phase 7: Post-Validation (LAST)
- Phase 8: Final Report

Auto-Fix Safety Rules

Only fix P3 and safe P2 issues
Never fix P0 or P1 (security/critical issues need human review)
Fix one category at a time
Verify changes with git diff after each category
If validation fails, REVERT all changes

Validation Rules

All 3 validators must PASS to keep fixes
If ANY validator fails:
- Revert changes: git reset --hard HEAD
- Document why in ISSUES.md
- Mark issues as "Needs manual fix"

Log Explosion Monitoring

Agent 7 monitors production systems for cost/reliability issues:

Axiom queries - Check log volume, empty logs, duplicates (last 15 min)
Sentry checks - Check error frequency, patterns, storms (last 24h)
Philosophy: Logs should be ROBUST but NOT EXCESSIVE
- ✅ Always log: errors, warnings, poor performance, critical events
- ❌ Don't log: successful operations at high frequency, duplicates, empty logs
Target: <1,400 logs/hour, 0 empty logs, <50 errors/hour
Auto-fixes: Empty log validation, sampling, deduplication, log level changes

ISSUES.md Update Rules

Update existing ISSUES.md, never create new file
Mark fixed issues with:
- Status: Fixed
- Fixed By: Auto-Fixer (Agent 8)
- Fixed Date: [TODAY]
- Validation: PASSED
Keep unfixed issues as Open
Add new issues from scanning

Expected Outputs

Modified Files

Modified:
- ISSUES.md (updated with findings and fixes)
- Multiple source files (console.logs removed, imports cleaned, etc.)

Created:
- maintenance-backup-[timestamp] branch (backup before changes)

Console Output

🔧 Code Maintenance - 13-Agent Swarm with Auto-Fix

═══════════════════════════════════════════════════════════════

Phase 0: Safety Checkpoint ✓ (30 sec)
───────────────────────────────────────
✓ Working directory has uncommitted changes
✓ Created pre-maintenance checkpoint commit
✓ Checkpoint: a5d413b
✓ Ready to proceed with maintenance

Phase 1: Initialization ✓ (1 min)
─────────────────────────────
✓ Loaded ISSUES.md (156 existing issues)
✓ Identified 47 files changed in last 7 days
✓ Created backup branch: maintenance-backup-1735142400
✓ Initialized 13-agent tracking

Phase 2: Parallel Scanning ⚡ (8 min)
────────────────────────────────────
→ Agent 1: Documentation Guardian      [COMPLETE] 12 findings
→ Agent 2: Issue Tracker Curator       [COMPLETE] 23 findings
→ Agent 3: Code Quality Sentinel       [COMPLETE] 45 findings
→ Agent 4: Architecture Enforcer       [COMPLETE] 31 findings
→ Agent 5: Performance & Security      [COMPLETE] 18 findings
→ Agent 6: Refactoring Specialist      [COMPLETE] 14 findings
→ Agent 7: Error & Log Explosion Mon.  [COMPLETE] 8 findings
  ⚠️  WARNING: 20,000 logs/hour (target: <1,400)
  🚨 CRITICAL: 172,618 empty logs in 15 min

Total findings: 151

Phase 3: Integration ✓ (2 min)
────────────────────────────────
→ Agent 8: Integration Validator [COMPLETE]
✓ Deduplicated 151 → 92 unique issues
✓ Identified 28 auto-fixable issues (includes log fixes)
✓ Prioritized: 5 P0, 19 P1, 39 P2, 29 P3

Phase 4: Auto-Fix ⚡ (4 min)
────────────────────────────────
→ Agent 9: Auto-Fixer [RUNNING]

Fixing console.log statements...
  ✓ Removed 7 console.log statements (7 files)

Fixing unused imports...
  ✓ Removed 12 unused imports (8 files)

Fixing ESLint auto-fixable issues...
  ✓ Fixed 5 ESLint violations (4 files)

Auto-fix summary:
  ✓ Fixed: 24 issues
  ✓ Files modified: 15
  ✓ Skipped: 0 issues

Phase 5: Parallel Validation ⚡ (3 min)
───────────────────────────────────────
→ Agent 10: Build & Type Validator   [COMPLETE] ✅ PASSED
→ Agent 11: Test Suite Validator     [COMPLETE] ✅ PASSED
→ Agent 12: Lint & Format Validator  [COMPLETE] ✅ PASSED

All validation checks passed! ✅

Phase 6: Final Reconciliation ✓ (1 min)
────────────────────────────────────────
→ Agent 13: Final Reconciliation [COMPLETE]
✓ Updated ISSUES.md
  - 28 issues marked as Fixed (includes log explosion fixes)
  - 64 new issues added
  - 12 existing issues updated
  - Log health: CRITICAL → HEALTHY (99.8% reduction)

Phase 7: Post-Execution Validation ✓ (4 min)
─────────────────────────────────────────────
📊 Changes since checkpoint (a5d413b):
  15 files changed, 0 insertions(+), 45 deletions(-)

→ Running test suite...
✅ All 247 tests passed

→ Running build...
✅ Build completed successfully (0 errors, 0 warnings)

→ Generating diff for review...
✅ All changes validated - safe to commit

═══════════════════════════════════════════════════════════════
✅ MAINTENANCE COMPLETE - VALIDATION PASSED
═══════════════════════════════════════════════════════════════

All changes validated successfully:
✅ Tests passed (247/247)
✅ Build successful
✅ Code quality maintained

Review changes above. If you want to keep them:
  git add .
  git commit -m 'Apply code maintenance fixes'

If you want to REVERT everything:
  git reset --hard a5d413b

Backup branch: maintenance-backup-1735142400

═══════════════════════════════════════════════════════════════

📊 FINAL SUMMARY

Issues:
┌──────────┬─────────┬─────────┬─────────┐
│ Priority │ Found   │ Fixed   │ Open    │
├──────────┼─────────┼─────────┼─────────┤
│ P0       │ 4       │ 0       │ 4       │
│ P1       │ 18      │ 0       │ 18      │
│ P2       │ 37      │ 8       │ 29      │
│ P3       │ 28      │ 16      │ 12      │
└──────────┴─────────┴─────────┴─────────┘

Auto-Fixed (24 issues):
✓ Removed 7 console.log statements
✓ Removed 12 unused imports
✓ Fixed 5 ESLint violations

Validation Results:
✅ TypeScript compilation: PASSED
✅ Test suite (247 tests): PASSED
✅ ESLint checks: PASSED

🚨 Critical Actions Required:
1. [P0] Add withAuth to upload endpoint (10 min)
2. [P0] Add RLS policies to exports table (20 min)
3. [P1] Fix 3 failing tests in timeline (1 hour)

📁 Updated Files:
✓ ISSUES.md
✓ 15 source files (auto-fixed)

Next Steps:
1. Review ISSUES.md for complete details
2. Address 4 P0 critical issues immediately
3. Plan sprint for 18 P1 high-priority issues

═══════════════════════════════════════════════════════════════

Quality Checks

Before marking complete, verify:

Safety Protocol:

Phase 0: Created checkpoint commit (if needed)
Phase 0: Recorded CHECKPOINT_COMMIT hash
Phase 7: Showed diff from checkpoint
Phase 7: Re-ran full test suite
Phase 7: Re-ran build
Phase 7: Provided rollback instructions to user
If tests/build failed, automatically rolled back

Agent Execution:

All 13 agents executed successfully
Agents 1-7 ran in PARALLEL (single message, 7 Tasks) ⚡
Agent 7 checked Axiom/Sentry for log/error explosions
Agents 10-12 ran in PARALLEL (single message, 3 Tasks) ⚡
Auto-fixes were validated before keeping
ISSUES.md updated (not new file created)
All findings have file:line references
Fixed issues marked with "Fixed By: Auto-Fixer"
Validation results included
Log health verified (robust but not excessive)

Codebase-Specific Intelligence

TypeScript/React Patterns:

Branded types for IDs (UserId, ProjectId, AssetId)
Discriminated unions for error handling
forwardRef for reusable components
Custom hooks following hooks order

API Security:

All routes use withAuth middleware
Rate limiting configured
Input validation with assertion functions
Service layer for business logic

State Management:

Zustand stores with Immer middleware
Separate stores by domain
Selector patterns for performance

Testing:

AAA pattern (Arrange-Act-Assert)
Helper functions in __tests__/helpers/
See TEST_RELIABILITY_GUIDE.md for flaky tests

Database:

RLS policies on all tables
Branded types for foreign keys
Proper indexing

Performance Optimization

Target: Complete in 20-30 minutes (including safety checks)

Phase breakdown:

Phase 0: Safety checkpoint (30 sec)
Phase 1-6: Agent execution (15-20 min)
Phase 7: Post-validation (3-5 min)

Optimization strategies:

Focus on files changed in last 7 days (git log)
Use parallel execution (agents 1-6, agents 9-11) ⚡ CRITICAL
Leverage Glob/Grep for pattern matching
Cache frequently accessed data
Skip node_modules, .next, binaries

Parallel execution saves 10-15 minutes:

Sequential agents 1-7: ~35 min → Parallel: ~8 min ✅
Sequential agents 10-12: ~9 min → Parallel: ~3 min ✅

Error Handling

If Agent Fails

If ANY scanning agent (1-7) fails:
→ Continue with remaining agents
→ Note failure in summary
→ Proceed with available findings

If Error Explosion Monitor (Agent 7) fails:
→ Continue with other agents
→ Log warning: "Could not check Axiom/Sentry - manual verification needed"
→ Proceed with remaining findings

If Integration Validator (8) fails:
→ STOP - cannot proceed safely
→ Report error to user
→ Do not auto-fix

If Auto-Fixer (9) fails:
→ Revert any partial changes
→ Mark issues as "Auto-fix failed"
→ Continue to reconciliation

If ANY validation agent (10-12) fails:
→ REVERT all auto-fixes immediately
→ Mark issues as "Needs manual fix"
→ Include validation errors in ISSUES.md

Rollback Procedure

Automatic rollback (Phase 7):

# If tests or build fail in Phase 7:
git reset --hard ${CHECKPOINT_COMMIT}
git clean -fd

Output: "✓ Rolled back to pre-maintenance state (${CHECKPOINT_COMMIT})"

Manual rollback (user choice):

# User can rollback anytime after reviewing changes:
git reset --hard ${CHECKPOINT_COMMIT}

# Alternative: Use backup branch
git reset --hard maintenance-backup-[timestamp]

# Backup branch cleanup (only after successful completion):
git branch -D maintenance-backup-[timestamp]

Three-layer safety:

Checkpoint commit - Exact starting point (Phase 0)
Backup branch - Alternate restore point (Phase 1)
Validation rollback - Automatic revert if tests/build fail (Phase 7)

Examples

User Trigger: "Run code maintenance" User Trigger: "Maintain the codebase" User Trigger: "Audit and fix code" User Trigger: "Daily maintenance check" User Trigger: "Clean up code and validate"

Notes

Follows Document Management Protocol (CLAUDE.md)
Never creates duplicate report files
Always consolidates into ISSUES.md
Auto-fixes are safe and validated
Can run daily for continuous improvement
Tailored to Next.js/React/TypeScript/Supabase stack

Install Skill

SKILL.md