same-results-less-code

Community Refactoring Best Practices: Same Results, Less Code

Code-review and refactoring guide focused on the parts of code volume that come from judgment and modelling gaps — wrong abstraction choices, hidden semantic duplication, defensive habits, premature generality. This skill deliberately skips what linters and tools like knip, eslint, ruff, tsc --noUnusedLocals, or formatters already catch. It is the second pass: after the mechanical cleanup, what remains?

Core Principles

1. Preserve behaviour. Every transformation must produce identical observable behaviour — same outputs, same errors, same side effects, same API surface.
2. Earlier mistakes cascade. A wrong frame multiplies into wrong shapes, which multiply into duplicate logic. Optimise from the top of the lifecycle.
3. Explain why, not just what. Each rule explains the cost of the anti-pattern so judgment can transfer to novel cases.
4. Quantify where possible. Prefer "eliminates N lines / prevents X bug class" over "cleaner."
5. Don't over-refactor. Rule of three: extract abstractions when duplication has actually appeared three times, not in anticipation.

When to Apply

Use this skill when:

• Reviewing a PR for "could this be simpler?" (the question linters can't answer)
• Refactoring code that has grown in volume without growing in capability
• Auditing a module that "feels heavy" — many flags, many layers, many checks
• Onboarding to an unfamiliar codebase and trying to spot the parts that are accidental volume vs essential complexity
• Designing a new module and wanting to avoid the common over-abstraction traps
• Working alongside knip / eslint / ruff and wanting the layer of judgment those tools can't supply

Don't use this skill for:

• Mechanical cleanup that a linter or formatter already does (unused imports, dead exports, style) — use knip, eslint, ruff, or prettier/black instead.
• Algorithmic complexity / performance tuning — use complexity-optimizer for that.
• General cleanup of recently modified code regardless of mental-model gaps — use code-simplifier.