Skip to content
Skills Library
Programming · Building & coding

simplification-pass

/simplification-pass

Removes complexity that is not paying for itself: dead code, needless abstraction, duplicated logic, and configuration nobody sets. Use when code is harder to read than the problem is hard, before extending a messy area, or when a diff can be made smaller without losing behavior. Never changes behavior.

Licence
MIT
Last repository change
26.09.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Removes complexity that is not paying for itself: dead code, needless abstraction, duplicated logic, and configuration nobody sets. Use when code is harder to read than the problem is hard, before extending a messy area, or when a diff can be made smaller without losing behavior. Never changes behavior.

Original author description

Removes complexity that is not paying for itself: dead code, needless abstraction, duplicated logic, and configuration nobody sets. Use when code is harder to read than the problem is hard, before extending a messy area, or when a diff can be made smaller without losing behavior. Never changes behavior.

How it works

  1. Preconditions
  2. What to look for, in order of payoff
  3. Chesterton's fence
  4. What is not simplification
  5. Process
  6. Verification
  7. Red flags
Original SKILL.md headings · 85 lines, 631 words
SKILL.md preview
---
name: simplification-pass
description: Removes complexity that is not paying for itself: dead code, needless abstraction, duplicated logic, and configuration nobody sets. Use when code is harder to read than the problem is hard, before extending a messy area, or when a diff can be made smaller without losing behavior. Never changes behavior.
license: MIT
metadata:
  phase: review
  owners: [senior-engineer, code-reviewer]
  version: "0.1.0"
---

# Simplification Pass

The goal is less code doing the same thing, verified by the same tests passing unchanged.
If the tests need editing, it was a behavior change, not a simplification.

## Preconditions

- Tests exist and pass before you start. Quote the run.
- The tests actually cover the behavior you are about to move. If they do not, write them
  first; simplification without a safety net is rewriting.
- This is its own commit, separate from any feature work.

## What to look for, in order of payoff

1. **Dead code.** Unreferenced functions, unreachable branches, a flag that is always the
   same value, a parameter every caller passes identically. Delete it; git remembers.

2. **Abstraction with one implementation.** An interface with a single implementer, a
   factory that constructs one type, a strategy pattern with one strategy. It was built for
   a second case that never arrived.

3. **Indirection that does not decide anything.** A wrapper that forwards, a config value
   nobody sets, a layer that only renames its arguments.

4. **Duplicated logic that has drifted.** Two copies that are slightly different is worse
   than two copies that are identical, because now nobody knows which is correct. Find out
   which is right before merging them; the difference may be a bug fix.

5. **Nesting.** Guard clauses and early returns flatten most deep conditionals. Three
   levels is usually one extraction away from one.

6. **Comments compensating for names.** Rename, then delete the comment.

7. **Options nobody uses.** Every flag doubles the state space. Remove the ones with one
   real value.

## Chesterton's fence

Before deleting something odd, find out why it is there. Two minutes:

- `git log -S` for the line, and read the commit message.
- Search for callers, including in tests, config, and other languages.
- Look for a comment or issue reference nearby.

If you find a reason, leave it and add the missing comment. If you find nothing after
looking, delete it and say in the commit message that you looked.

## What is not simplification

- Renaming everything to your preferred convention.
- Replacing a clear loop with a dense one-liner. Shorter is not simpler.
- Introducing a new abstraction to remove two lines of duplication. Two similar things are
  usually just two things.
- Changing behavior "because the old behavior looked wrong". That is a bug report, not a
  refactor.

Duplication is cheaper than the wrong abstraction. Wait for the third occurrence.

## Process

1. Run the tests. Quote the green run.
2. Make one kind of simplification. One commit.
3. Run the tests. They must pass **unchanged**.
4. Repeat.
5. Report the net line change and what was removed.

## Verification

- The tests are byte-for-byte unchanged and still pass.
- The diff removes more than it adds, or the addition is a name that removed a comment.
- No behavior changed. If any did, split it into its own commit with its own test.
- Anything deleted was checked against callers first.

## Red flags

| Thought | Reality |
|---------|---------|
| "I had to update a test" | Then it was a behavior change. Split it out. |
| "This abstraction will be useful later" | It has one implementation today. Delete it; adding it back is cheap. |
| "These two functions are similar, I'll merge them" | Find out why they differ first. The difference may be a fix. |
| "I do not know why this line is here, so it is dead" | Look. Two minutes of git history beats a regression. |
| "I'll simplify while adding the feature" | Separate commits, or the review is impossible. |
| "Shorter is simpler" | Not if it takes longer to read. Optimise for the reader. |

Versions

RepositoryScoreLicence
This page · khuynh22/agent-dev-team90MIT
gabigab117/cordeau100MIT

Database snapshot: 13.11.2026 · package version 0d56140f528c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100code-simplification
    Use when code works but is harder to read, maintain, or extend than it should be — after a feature lands, when review flags complexity, or when you hit deep nesting, long functions, high cyclomatic complexity, functions too tangled to test, two functions that do nearly the same…
  • 100code-simplification
    Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.
  • 100code-simplification
    Reduces complexity without changing observable behavior. Use when code is hard to read, duplicated, over-abstracted, or when a review asks for simplification and the existing tests must stay green.
  • 100spine-simplify
    Post-feature clarity pass — collapse needless indirection, delete dead code, flatten nesting, surface duplicated logic, fix altitude mismatches. Behavior-preserving only. Use when asked to "simplify this", "clean up this code", "reduce complexity", "this feels over-engineered",…
  • 90ring:planning-codebase-simplification
    Planning a whole-codebase simplification: audits a Go/TS codebase for needless abstraction and emits a KILL/REVIEW/KEEP plan plus a ring:running-dev-cycle task array. Plans only — no edits. Detects single-impl interfaces, pass-through shims, translation-free adapters, and…
  • 100code-simplification
    Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.