Skip to main content
skill CX Codex

same-results-less-code — Claude Code skill: simplify code and install

The same-results-less-code skill helps spot conceptual complexity during code review and refactoring while preserving behavior. It looks beyond the mechanical issues linters catch.

MIT 148 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill same-results-less-code -a claude-code
Open on GitHub

What same-results-less-code does

The guide examines code that grew through custom reinventions, poor abstraction choices, hidden duplication, or stored values that could be computed. Any proposed change should keep outputs, errors, side effects, and the API surface unchanged.

Its rules cover eight areas, including standard-library alternatives, abstraction shape, duplicated logic, derived state, excessive checks, and underused types. Think of it as a second pass after mechanical cleanup. For algorithmic complexity, it points to complexity-optimizer; for general cleanup of recently changed code, it points to code-simplifier.

Use it during PR review, when a module feels heavy, or while designing a new one. The guide recommends waiting until duplication has appeared three times before extracting an abstraction. For routine linting and formatting, use tools such as eslint or ruff instead.

What it helps with

  • spot unnecessary abstractions in a module
  • find semantic duplication behind different syntax
  • replace stored computed values with derivation
  • check whether code can be simplified without behavior changes
  • separate conceptual refactoring from lint cleanup

Example prompts for the agent

  • Review this PR and find simplifications that preserve behavior.
  • This module feels heavy; identify accidental complexity and excess abstractions.
  • Can this logic be shorter without changing its API or side effects?

How to install same-results-less-code

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill same-results-less-code -a claude-code

2Manually: put the files in place

~/.claude/skills/same-results-less-code/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/same-results-less-code/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about same-results-less-code

How do I install same-results-less-code in Claude Code?

Run npx skills add pproenca/dot-skills --skill same-results-less-code -a claude-code. The skill file is at ~/.claude/skills/same-results-less-code/SKILL.md.

What does same-results-less-code do?

It guides reviews and refactors toward conceptual sources of complexity, such as duplicated logic, unsuitable abstractions, and stored derived state. Changes should preserve observable behavior.

How is this different from a linter?

Linters and formatters handle mechanical issues; this skill examines the code’s conceptual model and abstraction choices. Apply it as a separate review pass after mechanical cleanup.

Source text

SKILL.md · MIT
---
name: same-results-less-code
description: Same behaviour in fewer, clearer lines — covers the judgment gaps that linters cannot catch (reinvention, wrong frame, hidden duplication, derived state, procedural rebuilds, speculative generality, defensive excess, type-system underuse). Trigger when reviewing, refactoring, or simplifying code — and even when the user doesn't explicitly ask for "simplification" but is reviewing code, refactoring, or asking "is there a shorter way to write this?". Complements knip/eslint/ruff/tsc by focusing on the conceptual modelling layer those tools cannot see.
---
# 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`](../complexity-optimizer/) for that.
- General cleanup of recently modified code regardless of mental-model gaps — use [`code-simplifier`](../../.curated/code-simplifier/).

## Rule Categories by Priority

| # | Category | Prefix | Impact | Rules | Gist |
|---|----------|--------|--------|-------|------|
| 1 | Reinvention | `reinvent-` | CRITICAL | 5 | You wrote what the platform/stdlib already provides |
| 2 | Wrong Frame | `frame-` | CRITICAL | 5 | Wrong abstraction shape — class where a function fits, manager nouns, OO over data |
| 3 | Hidden Duplication | `dup-` | HIGH | 5 | Semantic copies hiding behind syntactic differences |
| 4 | Derived State Stored | `derive-` | HIGH | 5 | Storing what should be computed |
| 5 | Procedural Rebuilds | `proc-` | MEDIUM-HIGH | 5 | Imperative reimplementation of declarative concepts |
| 6 | Speculative Generality | `spec-` | MEDIUM | 5 | Generality built for a second user who never arrived |
| 7 | Defensive Excess | `defense-` | MEDIUM | 4 | Checks for states the type/flow already rules out |
| 8 | Type System Underuse | `types-` | LOW-MEDIUM | 6 | Runtime guards that should be types |

## Quick Reference

### 1. Reinvention (CRITICAL)

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

### 2. Wrong Frame (CRITICAL)

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

### 3. Hidden Duplication (HIGH)

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

### 4. Derived State Stored (HIGH)

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

### 5. Procedural Rebuilds (MEDIUM-HIGH)

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

### 6. Speculative Generality (MEDIUM)

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

### 7. Defensive Excess (MEDIUM)

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

### 8. Type System Underuse (LOW-MEDIUM)

- [`types-discriminated-union-over-flags`](references/types-discriminated-union-over-flags.md) — Use a discriminated union instead of optional fields + tags
- [`types-literal-union-over-string`](references/types-literal-union-over-string.md) — Narrow `string` down to a literal union when the set is closed
- [`types-no-any-to-silence`](references/types-no-any-to-silence.md) — Avoid reaching for `any`/`as` to silence a type error
- [`types-branding-over-runtime-checks`](references/types-branding-over-runtime-checks.md) — Brand a validated value so you don't validate it twice
- [`types-exhaustive-switch-not-default`](references/types-exhaustive-switch-not-default.md) — Use exhaustiveness checks instead of a catch-all default
- [`types-readonly-and-immutable-by-default`](references/types-readonly-and-immutable-by-default.md) — 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](references/reinvent-stdlib-collection-ops.md) and [Frame](references/frame-function-not-class.md) — the biggest wins live there.
   - Then [Duplication](references/dup-parallel-types-same-shape.md) and [Derived state](references/derive-dont-store-computed.md).
   - Then [Procedural rebuilds](references/proc-loop-to-collection-method.md) and [Speculative generality](references/spec-interface-of-one.md).
   - 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

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

## Related Skills

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

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Code review and refactoring →

From the same set139

The whole set →
implementation-design-patterns implementation-design-patterns is a Claude Code skill that identifies a Gang of Four pattern from a problem description and explains when to apply or avoid it. CX Codex +1 151installs better-auth A TypeScript skill for Better Auth: instance setup, adapter choice, sessions and cookies, plugins, plus migration from another auth library. CX Codex +1 150installs diataxis diataxis sorts technical docs into four modes: tutorial, how-to, reference, explanation. Tells the agent which one a page needs before it starts writing. CX Codex +1 149installs drizzle-sqlite-scaffold drizzle-sqlite-scaffold generates boilerplate for Drizzle ORM + SQLite: config, client with pragmas, table schemas, CRUD modules and validators. Triggers on phrases like “add a table for X” or “set up the DB”. CX Codex +1 149installs codebase-comprehension-algorithms codebase-comprehension-algorithms maps an unfamiliar repository into feature domains: which files back a feature, where the architecture actually sits. CX Codex +1 148installs storybook This skill guides Storybook setup and story authoring for TypeScript/React components. Use it for interaction tests, accessibility checks, and component documentation. CX Codex +1 145installs code-map-visualization code-map-visualization tells the agent how to draw a codebase map that is already projected: which attribute goes on position, size or colour, and how to stay inside a 16 ms frame. CX Codex +1 145installs nuqs-scaffolder nuqs-scaffolder turns one JSON spec into four Next.js files for URL-backed filters: a parser map, a server loader, a client component and a Vitest test. CX Codex +1 145installs

Project sponsors

Companies that keep this analytics open