Code Perfection

Code Perfection — Autonomous Refactoring Agent

Enforced code refactoring and optimization skill. Uses mechanical scripts to drive a resolution loop that cannot exit until all issues are resolved or explicitly deferred. The agent does not choose whether to follow the loop — the scripts drive execution.

When to Activate

Use this skill when the user asks to:

• Refactor, optimize, or clean up code
• Audit a codebase for quality issues
• Fix multiple issues across files
• Run a code quality sweep
• Improve code without changing behavior
• Run verification checks on changes

Trigger phrases: "refactor", "optimize", "clean up", "code quality", "audit", "code perfection", "resolution loop", "fix all issues", "verify", "code sweep"

Commands

Command Flags

Architecture

All paths below are relative to $SKILL_DIR (the directory containing this file):

SKILL.md                    — this file (always loaded)
references/
  agents.md                 — core code standards (loaded into agent context)
  resolution-loop.md        — loop protocol + issue tracking
  audit.md                  — large codebase audit strategy
  parallel-vs-sequential.md — decision framework for parallel vs sequential
scripts/
  _lib.sh                   — shared library (colors, paths, helpers, atomic writes)
  verify.sh                 — 8-point verification checklist (exit 0/1)
  resolution-loop.sh        — issue ledger, lock, revert-on-failure, auto-commit
  audit-state.sh            — domain state management for large audits
  triage.sh                 — structural recon (discovers domains, classifies risk tiers)

Loading Strategy

References are loaded on-demand to minimize context usage:

Lazy loading rule: Do NOT read parallel-vs-sequential.md unless the agent is deciding between parallel and sequential execution for an audit. It is never needed for single-target refactoring.

Adaptive Behavior

The skill scales from 1-file fixes to 1000-file audits:

Execution

For /code-perfection <target>

1. Read $SKILL_DIR/references/agents.md — the core code standards
2. Read $SKILL_DIR/references/resolution-loop.md — the loop protocol
3. Determine scope from $ARGUMENTS:
   • If a path is given, use it as the target
   • If empty, use the current working directory
4. Initialize the resolution loop:

   "$SKILL_DIR/scripts/resolution-loop.sh" init <target>
   

5. Scan the target for issues — read the code, identify problems using the rules in agents.md
6. For each issue found, add it to the ledger:

   "$SKILL_DIR/scripts/resolution-loop.sh" add "<file>" "<line>" "<severity>" "<description>"
   

7. Enter the resolution loop (see references/resolution-loop.md for the full protocol):
   • Pick highest-severity OPEN issue
   • "$SKILL_DIR/scripts/resolution-loop.sh" start ISS-N
   • Fix the issue (one atomic change)
   • "$SKILL_DIR/scripts/verify.sh" — verify the fix
   • If passed: "$SKILL_DIR/scripts/resolution-loop.sh" resolve ISS-N
   • If failed: "$SKILL_DIR/scripts/resolution-loop.sh" fail ISS-N "<reason>"
   • "$SKILL_DIR/scripts/resolution-loop.sh" status — exit code 1 = continue, 0 = done, 2 = max iterations
   • NEVER ask "should I continue?" — the script decides.
8. When done: "$SKILL_DIR/scripts/resolution-loop.sh" report

For /code-perfection:audit <target>

1. Read $SKILL_DIR/references/agents.md
2. Read $SKILL_DIR/references/audit.md
3. Read $SKILL_DIR/references/resolution-loop.md
4. Run triage:

   "$SKILL_DIR/scripts/triage.sh" <target>
   "$SKILL_DIR/scripts/audit-state.sh" init <target>
   

5. Process domains in tier order (CRITICAL -> HIGH -> MEDIUM -> LOW):

   "$SKILL_DIR/scripts/audit-state.sh" next-domain
   "$SKILL_DIR/scripts/audit-state.sh" start-domain <name>
   # Run resolution loop on this domain
   "$SKILL_DIR/scripts/audit-state.sh" complete-domain <name>
   

6. After all domains: run boundary audit
7. Final report: "$SKILL_DIR/scripts/audit-state.sh" report

For /code-perfection:verify

Simply run:

"$SKILL_DIR/scripts/verify.sh"

Script Enforcement

The scripts enforce rules mechanically — agents cannot bypass them:

• verify.sh — auto-detects build system (TS/Rust/Go/Python/Elixir/Make), runs typecheck + tests + secret scan + dead code check. Exit 1 = change rejected.
• resolution-loop.sh — lockfile prevents concurrent writers, auto-reverts on failure, auto-defers after 3 attempts, auto-commits on resolve, checkpoint every 5 fixes. Exit code 0 = done, 1 = continue, 2 = max iterations exceeded.
• audit-state.sh — rejects start-domain if another domain is in_progress. Tracks per-domain issues/resolved/deferred. Resume-safe.
• triage.sh — classifies directories by risk tier (CRITICAL/HIGH/MEDIUM/LOW) without reading code. Pure filesystem scan.

Requirements

• python3 (required by resolution-loop.sh, audit-state.sh, and triage.sh for state management)
• git (required by resolution-loop.sh for revert-on-failure and auto-commit; verify.sh works without git but skips git-dependent checks)
• A build system (optional — verify.sh auto-detects and skips if missing)

Error Handling

Reinstallation

If scripts or references are missing:

# From the skill source directory:
./bin/code-perfection install

# Or install to a specific agent:
./bin/code-perfection install --agent claude-code