Auto Simplify
Overview
Make code easier to read and maintain while keeping exactly what it does — driven by an until-dry loop
where every edit must pass through a behavior-preservation gate before it counts. The discipline is what
makes it safe: simplification is the one refactor most likely to quietly change semantics, so each change
is minimal, verified, and reverted-on-doubt.
Phase 0: Scope, baseline, safety net
- Resolve scope (
$scope — the diff by default; a path/module otherwise).
- Establish the behavior baseline: the relevant tests are GREEN before you touch anything (if there are no
tests around the target, that's a gap — consider
auto-test first, or characterize behavior before
simplifying). In pipeline order this net already exists: auto-build lands a test with every task,
which is exactly why simplify runs after build. Record a snapshot of observable behavior for the target (inputs→outputs, key side effects).
- Open a
checkpoint-resume run.
Success criteria: scope fixed; a green baseline + behavior snapshot exist as the safety net.
Phase 1: Find simplification opportunities
Scan the scope for complexity that adds no behavior (prioritize by reader-cost):
- duplication — the same business logic in multiple places (DRY it — but not test DAMP);
- dead code — unreachable branches, unused exports/vars, commented-out blocks, debug output;
- over-abstraction — indirection/generalization with a single caller; a factory for one product;
- tangled control flow — deep nesting, redundant conditionals, boolean thickets that a guard clause or
early return would flatten;
- naming/structure — names or shapes that hide intent (fixable without behavior change).
For each, apply Chesterton's Fence: establish WHY it exists before proposing to remove/collapse it.
Success criteria: a prioritized list of concrete, behavior-neutral simplifications, each with its
purpose understood.
Phase 2: Simplify one thing, prove behavior preserved (converge until dry)
Run converge-loop in until-dry mode; per opportunity:
- Apply the smallest clarifying edit.
- Prove behavior-preserving (
adversarial-verify, regression lens): run the relevant tests — still
green? Then an adversarial check: does the edit change ANY observable output, side effect, error, or
edge-case behavior vs. the baseline snapshot? Consider the inputs a naive reader wouldn't (nulls,
empties, boundaries, concurrency). If any behavioral difference is found or suspected → REVERT.
- Keep or revert — keep only verified-neutral edits; a reverted one is recorded, not retried
identically.
Re-scan; exit when a round finds nothing more worth simplifying (dry) or it stalls.
Success criteria: each kept edit is verified behavior-preserving; the suite is green; no unverified
edit remains.
Phase 3: Report
Close the checkpoint and report: what was simplified (and the reader-cost it removed), what was
investigated-and-kept (Chesterton's Fence — with the purpose found), and anything reverted for failing the
behavior gate. Confirm the suite is green.
Success criteria: an honest account of kept / kept-on-purpose / reverted, with a green suite.
Common Rationalizations
| Rationalization |
Reality |
| "This code looks pointless, delete it." |
You not seeing the purpose isn't proof there is none. Establish why it's there (Chesterton's Fence) before removing. |
| "Fewer lines is simpler." |
Simpler = faster to understand, not shorter. A dense one-liner can be harder to read than the five lines it replaced. |
| "I'll refactor the whole module in one pass." |
A broad rewrite destroys the behavior-preservation signal and hides semantic changes. One verified edit at a time. |
| "Tests pass, so behavior is preserved." |
Tests are necessary, not sufficient — they may not cover the edge the edit changed. Add the adversarial semantic check. |
| "This abstraction might be needed later." |
Speculative generality with one caller is complexity now for a maybe-later. Inline it; re-abstract when a second caller actually arrives. |
| "It's clearly equivalent, no need to verify." |
"Clearly equivalent" is exactly where the subtle edge-case break hides. Verify or revert. |
Red Flags
- Behavior changed (an output/error/side effect differs) after a "simplification".
- Code removed without its purpose being established.
- A large multi-concern diff labeled "simplify".
- Tests weakened/deleted to make a simplification "pass".
- "Simpler" that's actually just terser and harder to read.
- The loop kept re-attempting the same reverted edit.
Guardrails
- Never change observable behavior; revert anything not provably neutral.
- Never remove code whose purpose you haven't established.
- Never do a broad rewrite; one small verified edit at a time.
- Never weaken tests to keep a simplification.
- Optimize for reader understanding, not line count or abstraction.
When To Load References
converge-loop (skill) — the until-dry simplification loop.adversarial-verify (skill) — the behavior-preservation (regression-lens) gate.checkpoint-resume (skill) — durable simplify-run state.auto-test (skill) — establish a test safety net first if the target is under-covered.
Output Contract
Report:
- scope + the behavior baseline used (tests green + snapshot)
- simplifications kept (reader-cost removed), each verified behavior-preserving
- code investigated and kept on purpose (Chesterton's Fence — the purpose found)
- edits reverted for failing the behavior gate
- final suite state (green)
1---2name: auto-simplify3description: Reduce a change's complexity WITHOUT changing behavior, provably: find duplication/dead code/over-abstraction in the diff, apply the smallest clarifying edit, then prove behavior preserved (tests green + adversarial semantic check) or REVERT — looping until dry. Respects Chesterton's Fence: never removes code whose purpose isn't established. Use when code works but reads worse than it should.4---56<EXTREMELY-IMPORTANT>7Simplification that changes behavior is a bug you introduced on purpose. Non-negotiable:81. BEHAVIOR IS PRESERVED, PROVABLY. Every edit keeps observable semantics identical. Proof = the full9 relevant test suite still passes AND an adversarial check finds no behavioral difference. Anything not10 provably behavior-preserving is REVERTED, not kept.112. CHESTERTON'S FENCE. Never remove or collapse code whose purpose you haven't established. "I don't see12 why this is here" is a reason to investigate, not to delete. If you can't explain what it guards,13 leave it and flag it.143. SMALLEST CLARIFYING EDIT. One simplification at a time, each independently verified. Never a broad15 rewrite "to clean it all up" — that erases the behavior-preservation signal and smuggles in changes.164. CLARITY OVER CLEVERNESS. The goal is code the next reader understands fastest — not the fewest lines17 or the most abstraction. A clever one-liner that's harder to read is not a simplification.185. FAIL CLOSED. The loop ends when a round finds nothing worth simplifying (dry) OR it stalls. It never19 reports "simplified" for edits it couldn't verify behavior-preserving.20</EXTREMELY-IMPORTANT>2122# Auto Simplify2324## Overview2526Make code easier to read and maintain while keeping exactly what it does — driven by an until-dry loop27where every edit must pass through a behavior-preservation gate before it counts. The discipline is what28makes it safe: simplification is the one refactor most likely to quietly change semantics, so each change29is minimal, verified, and reverted-on-doubt.3031## Phase 0: Scope, baseline, safety net3233- Resolve scope (`$scope` — the diff by default; a path/module otherwise).34- Establish the behavior baseline: the relevant tests are GREEN before you touch anything (if there are no35 tests around the target, that's a gap — consider `auto-test` first, or characterize behavior before36 simplifying). In pipeline order this net already exists: `auto-build` lands a test with every task,37 which is exactly why simplify runs after build. Record a snapshot of observable behavior for the target (inputs→outputs, key side effects).38- Open a `checkpoint-resume` run.3940**Success criteria:** scope fixed; a green baseline + behavior snapshot exist as the safety net.4142## Phase 1: Find simplification opportunities4344Scan the scope for complexity that adds no behavior (prioritize by reader-cost):4546- **duplication** — the same business logic in multiple places (DRY it — but not test DAMP);47- **dead code** — unreachable branches, unused exports/vars, commented-out blocks, debug output;48- **over-abstraction** — indirection/generalization with a single caller; a factory for one product;49- **tangled control flow** — deep nesting, redundant conditionals, boolean thickets that a guard clause or50 early return would flatten;51- **naming/structure** — names or shapes that hide intent (fixable without behavior change).5253For each, apply Chesterton's Fence: establish WHY it exists before proposing to remove/collapse it.5455**Success criteria:** a prioritized list of concrete, behavior-neutral simplifications, each with its56purpose understood.5758## Phase 2: Simplify one thing, prove behavior preserved (converge until dry)5960Run `converge-loop` in until-dry mode; per opportunity:61621. **Apply** the smallest clarifying edit.632. **Prove behavior-preserving** (`adversarial-verify`, regression lens): run the relevant tests — still64 green? Then an adversarial check: does the edit change ANY observable output, side effect, error, or65 edge-case behavior vs. the baseline snapshot? Consider the inputs a naive reader wouldn't (nulls,66 empties, boundaries, concurrency). If any behavioral difference is found or suspected → **REVERT**.673. **Keep or revert** — keep only verified-neutral edits; a reverted one is recorded, not retried68 identically.6970Re-scan; exit when a round finds nothing more worth simplifying (dry) or it stalls.7172**Success criteria:** each kept edit is verified behavior-preserving; the suite is green; no unverified73edit remains.7475## Phase 3: Report7677Close the checkpoint and report: what was simplified (and the reader-cost it removed), what was78investigated-and-kept (Chesterton's Fence — with the purpose found), and anything reverted for failing the79behavior gate. Confirm the suite is green.8081**Success criteria:** an honest account of kept / kept-on-purpose / reverted, with a green suite.8283## Common Rationalizations8485| Rationalization | Reality |86|---|---|87| "This code looks pointless, delete it." | You not seeing the purpose isn't proof there is none. Establish why it's there (Chesterton's Fence) before removing. |88| "Fewer lines is simpler." | Simpler = faster to understand, not shorter. A dense one-liner can be harder to read than the five lines it replaced. |89| "I'll refactor the whole module in one pass." | A broad rewrite destroys the behavior-preservation signal and hides semantic changes. One verified edit at a time. |90| "Tests pass, so behavior is preserved." | Tests are necessary, not sufficient — they may not cover the edge the edit changed. Add the adversarial semantic check. |91| "This abstraction might be needed later." | Speculative generality with one caller is complexity now for a maybe-later. Inline it; re-abstract when a second caller actually arrives. |92| "It's clearly equivalent, no need to verify." | "Clearly equivalent" is exactly where the subtle edge-case break hides. Verify or revert. |9394## Red Flags9596- Behavior changed (an output/error/side effect differs) after a "simplification".97- Code removed without its purpose being established.98- A large multi-concern diff labeled "simplify".99- Tests weakened/deleted to make a simplification "pass".100- "Simpler" that's actually just terser and harder to read.101- The loop kept re-attempting the same reverted edit.102103## Guardrails104105- Never change observable behavior; revert anything not provably neutral.106- Never remove code whose purpose you haven't established.107- Never do a broad rewrite; one small verified edit at a time.108- Never weaken tests to keep a simplification.109- Optimize for reader understanding, not line count or abstraction.110111## When To Load References112113- `converge-loop` (skill) — the until-dry simplification loop.114- `adversarial-verify` (skill) — the behavior-preservation (regression-lens) gate.115- `checkpoint-resume` (skill) — durable simplify-run state.116- `auto-test` (skill) — establish a test safety net first if the target is under-covered.117118## Output Contract119120Report:1211221. scope + the behavior baseline used (tests green + snapshot)1232. simplifications kept (reader-cost removed), each verified behavior-preserving1243. code investigated and kept on purpose (Chesterton's Fence — the purpose found)1254. edits reverted for failing the behavior gate1265. final suite state (green)
ulpi-io