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.

Rule Categories by Priority

Quick Reference

1. Reinvention (CRITICAL)

• reinvent-stdlib-collection-ops — Reach for .map/.filter/.reduce before writing loops
• reinvent-date-and-time — Stop hand-rolling date and time arithmetic
• reinvent-deep-equality — Use a real deep-equal instead of hand-recursing objects
• reinvent-explicit-state-machine — Surface a state machine instead of boolean flag juggling
• reinvent-builtin-data-structures — Recognise when a custom container is just a Map, Set, or Queue

2. Wrong Frame (CRITICAL)

• frame-function-not-class — Use a function when the class has no identity
• frame-manager-noun-is-a-verb — Rename Manager/Helper/Util classes until the real verb appears
• frame-composition-over-inheritance-for-shared-fields — Compose shared fields instead of inheriting
• frame-data-over-procedure — Model the problem as data before writing procedure
• frame-monolith-by-cohesive-axis — Split a god-function along its cohesive axis, not by line count

3. Hidden Duplication (HIGH)

• dup-parallel-types-same-shape — Collapse parallel types that share a shape
• dup-near-twin-functions — Parameterize two functions that differ by a literal
• dup-mirrored-branches — Lift shared lines out of mirrored if/else branches
• dup-config-not-copies — Replace many hardcoded copies with one table
• dup-cross-layer-shape — Collapse identical DTOs, DB rows, and domain objects

4. Derived State Stored (HIGH)

• derive-dont-store-computed — Compute what you can compute; store only what you can't
• derive-single-source-of-truth — Pick one source of truth; derive the rest
• derive-boolean-from-data — Derive booleans from the data, don't track them separately
• derive-cache-as-getter-not-field — Turn cached fields into getters until profiling proves otherwise
• derive-url-as-state — Let the URL or route be the state, not a mirror of it

5. Procedural Rebuilds (MEDIUM-HIGH)

• proc-mutation-builder-over-pipeline — Compose pipelines when the mutation-builder hides the intent
• proc-if-chain-as-lookup — Replace if/elif returning constants with a lookup table
• proc-manual-recursion-of-walk — Use a recognised tree/object walk, not hand-coded recursion
• proc-build-vs-declarative-template — Use the declarative form when the framework provides one
• proc-sequential-awaits-could-be-parallel — Parallelise independent awaits