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

6. Speculative Generality (MEDIUM)

• spec-interface-of-one — Avoid defining an interface for a single implementation
• spec-options-bag-of-one — Avoid options bags where every caller passes the same values
• spec-flag-driven-paths — Split a function that a boolean flag has made into two
• spec-no-extension-point-without-extender — Delete extension points that have no second user
• spec-generic-over-one-type — Drop the generic parameter when only one concrete type uses it

7. Defensive Excess (MEDIUM)

• defense-guard-against-impossible — Stop guarding against states the type/flow already rules out
• defense-validate-once-at-boundary — Validate once at the boundary, trust inside
• defense-let-it-throw — Let exceptions propagate; don't catch what you can't handle
• defense-null-pollution-from-bad-modelling — Fix the type that makes the null checks necessary

8. Type System Underuse (LOW-MEDIUM)

• types-discriminated-union-over-flags — Use a discriminated union instead of optional fields + tags
• types-literal-union-over-string — Narrow string down to a literal union when the set is closed
• types-no-any-to-silence — Avoid reaching for any/as to silence a type error
• types-branding-over-runtime-checks — Brand a validated value so you don't validate it twice
• types-exhaustive-switch-not-default — Use exhaustiveness checks instead of a catch-all default
• types-readonly-and-immutable-by-default — Mark data readonly until mutation is actually needed

How to Apply (Workflow)

When asked to review or refactor code with this skill:

1. Run the mechanical pass first. knip/eslint/ruff/tsc --noUnusedLocals will catch dead code, unused imports, style. Don't duplicate that work here.
2. Read the file or PR for intent. Ask: what is this code trying to do? The judgment skill is recognising when the implementation overshoots the intent.
3. Walk the categories in priority order.
   • Start with Reinvention and Frame — the biggest wins live there.
   • Then Duplication and Derived state.
   • Then Procedural rebuilds and Speculative generality.
   • Defensive and type-system issues last — they're high frequency but localised.
4. Propose minimal-diff transformations. Each rule shows incorrect → correct as a tight diff; preserve that property in suggestions.
5. Verify behaviour. Outputs, errors, and side effects must be identical. Tests must still pass.
6. Don't bundle unrelated changes. Each transformation should map to one category. Mixing them makes the change hard to review.

When NOT to Apply

• Code is younger than the rule of three (one or two duplicates) — extracting is premature.
• The pattern is genuinely a known exception (see each rule's "When NOT to use this pattern" section).
• The refactor would be a large, risky rewrite without a clear test safety net — propose, don't execute.
• Performance-critical hot paths where the "simpler" form has measurable cost — measure first.

Reference Files

Related Skills

• code-simplifier — Mechanical simplification (naming, dead code, nesting). Complementary first pass.
• complexity-optimizer — Algorithmic/performance complexity. Different axis.
• refactor — General-purpose refactoring workflow.
• clean-code — Broader clean-code principles. This skill is the narrower, judgment-focused subset.