@paperclip-skills/code-simplifier

Reviews code for unnecessary complexity and simplifies it while preserving all behavior. Targets recently modified code by default. Produces minimal, readable, correct code.

---

When to Use

Activate when:

• User asks to "simplify this", "clean up this code", "make this simpler", "reduce complexity"
• User says "this is too complicated", "over-engineered", "can we simplify"
• After completing a feature — run as a self-review pass before committing
• When reviewing code that feels harder to read than it should be

---

Steps

1 — Identify the target

If the user points to specific files, use those. Otherwise, find recently changed files:

git diff --name-only HEAD~3    # last 3 commits
git diff --cached --name-only  # staged changes

Read the target files fully before suggesting changes.

2 — Scan for simplification opportunities

Check each pattern in order. Fix what you find, skip what's clean.

| Pattern | Symptom | Fix | |---------|---------|-----| | Dead code | Unused imports, unreachable branches, commented-out blocks | Delete it | | Premature abstraction | Helper/utility used exactly once | Inline it | | Over-configuration | Options/flags no caller uses | Remove them | | Redundant wrappers | Function that just calls another function | Collapse to direct call | | Verbose conditionals | Nested if/else that could be a ternary or early return | Flatten with early returns | | Type ceremony | Explicit types where inference works | Let the compiler infer | | Copy-paste duplication | 3+ near-identical blocks | Extract only if genuinely reused | | Defensive overkill | Null checks on values that can never be null | Remove impossible guards | | String concatenation | Manual string building | Use template literals | | Callback nesting | Deeply nested .then() chains | Convert to async/await | | Magic numbers/strings | Unexplained literal values used more than once | Extract to named constant | | Feature flags for shipped features | Flags that are always on | Remove the flag, keep the code |

3 — Apply the simplification

Rules:

• Preserve all behavior — simplification must not change what the code does
• One concern per change — don't mix simplification with feature work
• Prefer deletion over modification — the best code is no code
• Three similar lines > a premature abstraction — don't abstract for one use case
• Don't add comments to explain simple code — if it needs a comment, it might not be simple enough
• Don't refactor test files unless they test the code being simplified
• Don't touch code you weren't asked about unless it's dead code from your changes

4 — Verify

After making changes:

# Run existing tests to confirm behavior is preserved
npm test          # or the project's test command
npx tsc --noEmit  # type check if TypeScript

If tests fail, the simplification broke something — revert and try a smaller change.

5 — Report

Summarize what was simplified and why. Format:

Simplified [file]:
- Removed [what] — [why it was unnecessary]
- Inlined [what] — [only used once]
- Flattened [what] — [early returns replace nesting]

---

Reference

Decision framework

Ask these questions about any piece of code:

1. Can I delete it? If nothing breaks, delete it.
2. Can I inline it? If it's used once, inline it.
3. Can I flatten it? If it's nested, use early returns.
4. Can I merge it? If two things do the same job, keep one.
5. Can I rename it? If the name doesn't explain it, rename it.

What NOT to simplify

• Code with extensive test coverage that works fine — don't fix what isn't broken
• Performance-critical hot paths — simplicity sometimes costs performance
• Code you don't understand yet — read first, simplify second
• External API contracts or public interfaces — these have downstream consumers