/refactoring [target]

Systematically refactor code. ALL identified issues must be fixed.

No arguments? Describe this skill and stop. Do not execute.

First: Activate Workflow

mkdir -p .claude && echo '{"skill":"refactoring","started":"'$(date -Iseconds)'"}' > .claude/active-workflow.json

Craft Standards (MANDATORY)

Refactor toward code a master craftsperson would be proud of.

The goal is code that looks like it was written by a skilled human engineer, not generated by AI.

AI Antipatterns to ELIMINATE

In addition to standard refactoring, actively hunt and remove:

• •Over-abstraction (factories/wrappers used only once → inline them)
• •Defensive paranoia (null checks where null is impossible → remove them)
• •Comment spam (// increment counter → delete it)
• •Speculative features (config options nobody uses → remove them)
• •Wrapper classes that add no value → unwrap them
• •Enterprise patterns in simple code → simplify ruthlessly

Human Craft to ACHIEVE

After refactoring, code should have:

• •Functions that do exactly one thing
• •Names so clear they don't need comments
• •No code a senior engineer would delete
• •Every abstraction justified by actual use

Test: Would someone reviewing this PR say "why is this here?" If yes, remove it.

⚠️ STRICT REQUIREMENTS - NO JUDGMENT CALLS

You MUST check for and FIX all of these issues. Not "consider" - FIX:

1. •FUNCTIONS > 30 LINES - Split them. No exceptions.
2. •FILES > 300 LINES - Split into focused modules. Create thin re-export index if needed.
3. •COMPLEXITY > 10 - Cyclomatic complexity too high. Flatten with early returns, extract helpers.
4. •VAGUE NAMES - Rename data/result/temp/item/info to meaningful names.
5. •DUPLICATE CODE - Extract to shared function. Run lens dedupe to find cross-file duplications.
6. •CROSS-FILE DUPLICATION - Same function in multiple files → extract to utils/.
7. •DEEP NESTING - Flatten with early returns.
8. •MAGIC NUMBERS/STRINGS - Extract to named constants.
9. •MISSING ERROR HANDLING - Add it.
10. •GOD FILES - Split files with multiple concerns.

FORBIDDEN (Phase will FAIL if detected):

• •Saying "could be improved" without fixing
• •Skipping issues because they're "minor"
• •Suggesting future refactorings instead of doing them
• •Leaving any identified issue unfixed
• •Tests failing after refactoring

Process

Step 0: Load Expert Guidance

Before starting, read these canon skills and apply their principles throughout:

Always load (base brain — all 10):

1. •canon/clarity/SUMMARY.md
2. •canon/pragmatism/SUMMARY.md
3. •canon/simplicity/SUMMARY.md
4. •canon/composition/SUMMARY.md
5. •canon/distributed/SUMMARY.md
6. •canon/data-first/SUMMARY.md
7. •canon/correctness/SUMMARY.md
8. •canon/algorithms/SUMMARY.md
9. •canon/abstraction/SUMMARY.md
10. •canon/optimization/SUMMARY.md

Then load (domain-specific): 11. canon/design-patterns/SUMMARY.md 12. canon/refactoring/SKILL.md

Auto-detect domain canon (check files, load matches):

If a skill file doesn't exist (not installed in this project), skip it and continue. List loaded experts in EXPERTS_LOADED. Tag each fix with (via [expert-skill]) showing which expert drove it.

Step 0b: Learn From Past Mistakes

Read both lessons files if they exist:

1. •.claude/universal-lessons.md — universal patterns (ships with skills, applies to all projects)
2. •.claude/lessons.md — project-specific patterns (accumulated from this project's runs)

Add relevant lessons to your checklist of things to look for:

• •CODE_QUALITY entries → actively hunt for these patterns (e.g., dead exports, unused imports, redundant verification reads)
• •LOGIC entries → check for these bug patterns during refactoring (e.g., TOCTOU, missing validation)
• •AI_SMELL entries → look for single-use helpers to inline, JSDoc restating function names, impossible null checks, empty catch blocks

If a file doesn't exist, skip it and continue.

Step 1: Identify Issues

1. •Identify Issues - Find all code quality problems
2. •Fix Each One - Use Edit tool to fix
3. •Run Tests - Verify behavior preserved
4. •Report - Document what was fixed

REQUIRED Output Format

## Refactoring: [target]

ISSUES_IDENTIFIED:
- [file:line] [issue type] [description]
- [file:line] [issue type] [description]

REFACTORED:
- [file:line] [issue type] - FIXED: [what was done] (via [expert-skill])
- [file:line] [issue type] - FIXED: [what was done] (via [expert-skill])

ISSUES_REMAINING: 0 (must be zero)

REFACTOR_COUNT: N

TESTS_PASS: yes

EXPERTS_LOADED: [list of skill names actually read]

REFACTORING_COMPLETE

Evidence Checklists (MANDATORY)

After refactoring, produce three evidence checklists. Write each to .claude/evidence/ (create directory if needed).

Checklist 4a: Name Sufficiency

Review EVERY exported function and constant. Write to .claude/evidence/refactor-4a.md:

# Evidence: Refactor 4a — Name Sufficiency

| Location | Item | Verdict | Reasoning |
|----------|------|---------|-----------|
| src/foo.ts:barFunction | Name describes behavior | PASS | Name clearly indicates what it does |
| src/baz.ts:processData | Vague name | FAIL | 'processData' says nothing about what processing occurs |

Checklist 4b: Single Responsibility

Review EVERY exported function. Write to .claude/evidence/refactor-4b.md:

# Evidence: Refactor 4b — Single Responsibility

| Location | Item | Verdict | Reasoning |
|----------|------|---------|-----------|
| src/foo.ts:createUser | Does one thing | PASS | Only creates user record |
| src/bar.ts:handleRequest | Multiple concerns | FAIL | Validates, transforms, saves, and logs |

Checklist 4c: Magic Values

Review for magic numbers and strings. Write to .claude/evidence/refactor-4c.md:

# Evidence: Refactor 4c — Magic Values

| Location | Item | Verdict | Reasoning |
|----------|------|---------|-----------|
| src/config.ts:10 | Timeout 5000 | PASS | Named constant TIMEOUT_MS |
| src/auth.ts:24 | Literal "admin" | FAIL | Role string should be a constant |

Every row must have a PASS or FAIL verdict. No blanks. The machine gate validates row counts against codebase counters — incomplete checklists block the pipeline.

Pipeline Constraints

When running as part of a pipeline (called by /build or /improve):

SCOPE CONSTRAINT: Only modify code directly related to issues you identify. Do not refactor, rename, or restructure code that was not flagged as an issue.

COMPLEXITY BUDGET: After your changes, the codebase must have the same or fewer: files, exported functions, types/interfaces, and total lines. If your fix adds lines, find lines elsewhere to remove. Net-zero or net-negative. EXCEPTION: Security fixes are exempt.

NO SILENT FAILURES: Do not change a throw/crash to a log-and-continue. Fail-fast on misconfiguration is always correct.

Validation (Phase will FAIL if violated)

• •ISSUES_REMAINING > 0
• •TESTS_PASS: no
• •Issues identified but not in REFACTORED section
• •Any file > 300 lines after refactoring
• •Any function with cyclomatic complexity > 10 after refactoring
• •Evidence checklists missing or incomplete

🛑 MANDATORY STOP

After refactoring:

• •DO NOT proceed to next phase
• •DO NOT continue with "let me also..."

Your turn ends here. Output REFACTORING_COMPLETE and STOP.