Simplify
Make a change simpler and clearer without changing what it does. The bar: readable, explicit code over
clever, compact code — would a senior engineer call this overcomplicated? Scope is the recently
changed code — the working diff (e.g. git diff against the branch point) unless the caller names
files. This is quality-only: it does not hunt for bugs (that's review).
Step 0 — the invariant
Preserve functionality. Never change what the code does, only how it does it. Every original
feature, output, and behavior stays intact. If a simplification would alter behavior, it is a review
or implementation concern, not a simplification — stop and surface it.
Scan — three buckets
Look at the changed code for:
- Structural — nesting depth ≥ 3, functions longer than ~50 lines, nested ternaries, boolean-flag
parameters that select behavior, indirection that only forwards a call.
- Naming —
data/result/temp/foo, names that mislead, names that imply something broader or
different than the thing actually is.
- Redundancy — duplicated logic, dead/unreachable code, unused parameters/variables/fields,
over-abstraction (a helper, wrapper, or interface used in exactly one place), defensive code for
states an upstream invariant already makes impossible.
The deletion test
For each abstraction or layer of indirection, ask: would removing it concentrate complexity
(then keep it — it's earning its keep) or merely relocate it (then remove it — it's not)? A
single-use helper usually relocates; inline it. A wrapper that hides a genuinely complex subsystem
behind a small interface usually concentrates; keep it.
Two-sided guardrail
Simplifying is a balance, not a race to fewer lines. Pair every "look for" with a "don't":
| Look for |
Don't |
| reduce nesting and indirection |
introduce a nested ternary or a dense one-liner |
| inline a single-use helper |
inline a helper that names a genuinely complex step |
| remove a redundant abstraction |
remove a helpful abstraction that organizes the code |
| consolidate duplicated logic |
merge unrelated concerns into one function |
| clearer names, fewer obvious comments |
make the code harder to debug or extend |
If the "simplified" version is longer or harder to follow, it isn't a simplification — revert it.
Process
- Establish a baseline. Run the tests covering the change — or, if there is no suite or it cannot
run, the narrowest available behavior check (build, typecheck, or lint) — and confirm it is green
before you start. Never fabricate a green result; if the baseline is already red for unrelated
reasons, note that and rely on the narrower check.
- Understand before changing (Chesterton's Fence). Work out why the code is shaped the way it
is — a guard, retry, or special case may exist for a real reason. Remove a guard only when its
premise is verifiable in the code you can see; if confirming it needs reasoning about whether an
upstream invariant truly holds, leave it and flag for
review.
- One simplification at a time → re-run that check → keep it only if it stays green; revert
immediately if not. Tests are necessary but not sufficient: for a change on a path the suite does
not exercise, reason explicitly about input/output equivalence — error paths, ordering, side
effects, short-circuit evaluation — before keeping it.
- Tests are out of scope. Never edit a test to make it pass — a breaking test means behavior
changed, so revert the simplification, not the test. Do not refactor, consolidate, or delete tests
or fixtures even when they look redundant; that silently weakens coverage.
- Keep the simplify diff separate from feature/fix changes, so a reviewer reads pure refactor.
- Verify functionality preserved at the end: the baseline check is green and you have reasoned
about any untested paths you touched.
Red flags
- The simplified code is longer, or harder to follow, than before.
- Editing, consolidating, or deleting a test or fixture (tests are out of scope).
- Calling behavior "unchanged" from a passing suite alone, on code the suite does not exercise.
- Removing an abstraction or guard without applying the deletion test / Chesterton's Fence.
- Touching code outside the working diff ("while I'm here…").
- Optimizing for fewer lines at the cost of clarity.
Verification checklist
1---2name: simplify3description: Reduce complexity in recently changed code — cut needless abstraction, dead code, and duplication; improve names and structure — WITHOUT changing behavior. Quality only; it does not hunt for bugs (use review for that). Use after implementing a chunk of work, before review, or whenever a diff feels more complicated than the problem it solves. Triggers on "clean this up" / "tidy this" / "refactor this" when code already exists; for an underspecified goal with no code yet, use `clarify`.4---56# Simplify78Make a change simpler and clearer without changing what it does. The bar: readable, explicit code over9clever, compact code — would a senior engineer call this overcomplicated? Scope is the **recently10changed code** — the working diff (e.g. `git diff` against the branch point) unless the caller names11files. This is quality-only: it does not hunt for bugs (that's `review`).1213## Step 0 — the invariant1415**Preserve functionality. Never change what the code does, only how it does it.** Every original16feature, output, and behavior stays intact. If a simplification would alter behavior, it is a `review`17or implementation concern, not a simplification — stop and surface it.1819## Scan — three buckets2021Look at the changed code for:2223- **Structural** — nesting depth ≥ 3, functions longer than ~50 lines, nested ternaries, boolean-flag24 parameters that select behavior, indirection that only forwards a call.25- **Naming** — `data`/`result`/`temp`/`foo`, names that mislead, names that imply something broader or26 different than the thing actually is.27- **Redundancy** — duplicated logic, dead/unreachable code, unused parameters/variables/fields,28 over-abstraction (a helper, wrapper, or interface used in exactly one place), defensive code for29 states an upstream invariant already makes impossible.3031## The deletion test3233For each abstraction or layer of indirection, ask: would removing it **concentrate** complexity34(then keep it — it's earning its keep) or merely **relocate** it (then remove it — it's not)? A35single-use helper usually relocates; inline it. A wrapper that hides a genuinely complex subsystem36behind a small interface usually concentrates; keep it.3738## Two-sided guardrail3940Simplifying is a balance, not a race to fewer lines. Pair every "look for" with a "don't":4142| Look for | Don't |43|---|---|44| reduce nesting and indirection | introduce a nested ternary or a dense one-liner |45| inline a single-use helper | inline a helper that names a genuinely complex step |46| remove a redundant abstraction | remove a helpful abstraction that organizes the code |47| consolidate duplicated logic | merge unrelated concerns into one function |48| clearer names, fewer obvious comments | make the code harder to debug or extend |4950If the "simplified" version is longer or harder to follow, it isn't a simplification — revert it.5152## Process53541. **Establish a baseline.** Run the tests covering the change — or, if there is no suite or it cannot55 run, the narrowest available behavior check (build, typecheck, or lint) — and confirm it is green56 before you start. Never fabricate a green result; if the baseline is already red for unrelated57 reasons, note that and rely on the narrower check.582. **Understand before changing (Chesterton's Fence).** Work out *why* the code is shaped the way it59 is — a guard, retry, or special case may exist for a real reason. Remove a guard only when its60 premise is verifiable in the code you can see; if confirming it needs reasoning about whether an61 upstream invariant truly holds, leave it and flag for `review`.623. **One simplification at a time** → re-run that check → keep it only if it stays green; revert63 immediately if not. Tests are necessary but not sufficient: for a change on a path the suite does64 not exercise, reason explicitly about input/output equivalence — error paths, ordering, side65 effects, short-circuit evaluation — before keeping it.664. **Tests are out of scope.** Never edit a test to make it pass — a breaking test means behavior67 changed, so revert the simplification, not the test. Do not refactor, consolidate, or delete tests68 or fixtures even when they look redundant; that silently weakens coverage.695. **Keep the simplify diff separate** from feature/fix changes, so a reviewer reads pure refactor.706. **Verify functionality preserved** at the end: the baseline check is green and you have reasoned71 about any untested paths you touched.7273## Red flags7475- The simplified code is longer, or harder to follow, than before.76- Editing, consolidating, or deleting a test or fixture (tests are out of scope).77- Calling behavior "unchanged" from a passing suite alone, on code the suite does not exercise.78- Removing an abstraction or guard without applying the deletion test / Chesterton's Fence.79- Touching code outside the working diff ("while I'm here…").80- Optimizing for fewer lines at the cost of clarity.8182## Verification checklist8384- [ ] The baseline check (tests for the changed code, or build/typecheck/lint) is green before and after — never a fabricated green.85- [ ] For any change on a path the suite does not cover, I reasoned about input/output equivalence, not just "tests pass".86- [ ] No test or fixture was edited, consolidated, or deleted — tests stayed out of scope.87- [ ] Every removed abstraction/guard passed the deletion test (and Chesterton's Fence for guards).88- [ ] The change stayed within the working diff.89- [ ] The diff is genuinely clearer — not merely shorter.
ronaknnathani