Refactor
Improve existing code without changing behavior — split large functions, backfill tests, simplify.
by helderberto · MIT
The skill
Improve existing code without changing behavior — split large functions, backfill tests, simplify. Use when asked to "refactor", "make robust", "bulletproof", "strengthen", "add missing tests", "split functions", "simplify", "clean up", or "reduce complexity". Don't use for new features (/tdd), security (/harden), or PR review.
Refactor
Target: $ARGUMENTS (file, directory, or module — if blank, use unstaged changes)
Behavior is frozen — the test suite is the contract. Green before and after; if a test's meaning has to change, you've gone too far.
Workflow
1. Scope
- Identify target files (blank → unstaged changes)
- Locate each file's tests using the project's convention (co-located,
__tests__/,tests/,spec/). A file with no tests gets Test gaps items first — Split/Simplify on untested code is unverifiable, so backfill or skip. No test runner at all → ask which to use. UI flows → backfill end-to-end tests: call the Skill tool withtdd, which holds the UI-tests reference. Entrypoint scripts without exports → audit only. - Run the suite. If red, stop — don't refactor broken code
2. Audit
List findings, most-impactful first:
| Bucket | What to look for | Fix |
|---|---|---|
| Split | Functions > 20 lines, multiple responsibilities, I/O mixed with logic | Extract pure logic into named helpers; keep I/O at the edges; preserve the original signature |
| Edge cases | Missing null/empty/boundary checks at system boundaries, unhandled error paths | Test first, then guard |
| Test gaps | Untested public functions, uncovered branches, missing sad-path tests | Backfill through the public interface |
| Simplify | Nesting > 2 levels, dead code / unused params, duplicated logic, dense one-liners, shallow pass-through wrappers, speculative config never used, unclear names / primitive obsession | Guard clauses, delete, extract one helper, expand, inline (call the Skill tool with codebase-design for the deletion test), remove, rename to intent / small type |
Chesterton's Fence: before removing anything, explain why it's there. If you can't, leave it and flag it.
Present the audit as a checklist and ask which items to address — "All items" first, marked (Recommended).
3. Apply — one item at a time
Per approved item: RED (failing test exposing the gap, when the item adds behavior coverage) → GREEN (minimal change) → run tests. Real values over mocks; mock only external I/O (call the Skill tool with tdd for its mocking guide). If red after the change, revert it and flag as blocked. Never batch.
4. Report
Items addressed, tests added, functions extracted, items skipped with reason (Chesterton), suite result before/after.
Use this skill
Connect your agent to the Skill Store MCP server and ask for it by ref: helderberto/refactor-64208515341.
Details
- Publisher
- helderberto
- Category
- Software Development › Testing & QA
- License
- MIT
- Updated
- 2026-10-16
References
More from helderberto
- A11Y Audit Audit accessibility (WCAG) in frontend code.
- Architecture Audit Surface architectural friction across a codebase and propose deep-module refactors as RFCs.
- Build Implement the next unblocked ticket test-first and commit it, or fan every ticket out to parallel…
- Check Validate code quality — auto-fix formatting/lint, verify types, run tests.