helderberto Code Simplify
Make working code clearer without changing what it does. Clarity over cleverness. Behavior is frozen — the test suite is the contract. Applies to frontend and backend equally.
Target: $ARGUMENTS (file, directory, or module — if blank, use unstaged changes)
Guardrails
- Chesterton's Fence — before removing anything, explain why it's there. If you can't, leave it and flag it. Never delete guards, checks, or branches you don't understand.
- Behavior is frozen — no functional changes. Green test suite before and after; if a test's meaning has to change, you've gone too far.
- Clarity over cleverness — a junior should read it without decoding. Prefer boring and obvious.
Workflow
1. Baseline
- Identify target files (blank → unstaged changes)
- Run the test suite. If red, stop — don't simplify broken code
- If a target has no tests, flag it: simplification is unverifiable without them (offer
/fortify)
2. Audit
List findings, most-impactful first:
| Smell | Simplification |
|---|---|
| Deep nesting (> 2 levels) | Guard clauses / early return |
| Dead code, unused params, unreachable branches | Delete (after Chesterton's Fence) |
| Duplicated logic | Extract one named helper |
| Clever one-liners, dense ternaries | Expand to readable form |
| Shallow pass-through wrapper | Inline it (/codebase-design — the deletion test) |
| Speculative flexibility / config never used | Remove |
| Unclear names, primitive obsession | Rename to intent |
Present the audit. Ask which items to apply — list each as an option, "All items" first and marked (Recommended). Use AskUserQuestion (multiSelect) when available; otherwise a numbered checklist.
3. Apply — one change at a time
Per approved item:
- Make the single change
- Run tests — must stay green
- If red → revert that change, flag as blocked
Never batch. Use immutable edits — introduce no new mutation.
4. Report
## Simplify Report
### Applied
- Flattened `parseConfig` — 4 nesting levels → guard clauses
- Deleted unused `legacyMode` param (Chesterton: git blame shows the feature was removed)
- Inlined `wrapResult` pass-through (deletion test: complexity vanished)
### Skipped / Blocked
- `retryLoop` — kept the sleep; couldn't confirm why (Chesterton's Fence)
### Result
Tests: 42 passed | 0 failed | behavior unchanged
Relationship to neighbors
- Depth framing — reach for
/codebase-designvocabulary (deletion test, shallow module) when a simplification is really an interface question. - Splitting God functions or backfilling coverage →
/fortify(it changes structure and adds tests; this skill only removes complexity). - Restructuring across modules →
/architecture-audit.
Rules
- Never change external behavior — simplification is internal only
- Every removal passes the Chesterton's Fence test or gets flagged, not deleted
- Skip files with no test infrastructure unless the user opts in