auto-simplify

name	auto-simplify
version	0.1.0
disable-model-invocation	true
user-invocable	true
description	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.
allowed-tools	["Bash","Read","Edit","Write","Grep","Glob","Agent","Workflow"]
effort	high
argument-hint	[scope — a diff, path, or module] (default: the current diff)
arguments	["scope"]
when_to_use	Use when code works but is harder to read or maintain than it should be — after a build, on a messy module, or to pay down a specific bit of complexity. Do NOT use to change behavior, fix bugs, add features, or optimize for speed (that's auto-build / auto-performance); simplification that alters observable behavior is a refactor gone wrong, not a simplification.

Simplification that changes behavior is a bug you introduced on purpose. Non-negotiable: 1. BEHAVIOR IS PRESERVED, PROVABLY. Every edit keeps observable semantics identical. Proof = the full relevant test suite still passes AND an adversarial check finds no behavioral difference. Anything not provably behavior-preserving is REVERTED, not kept. 2. CHESTERTON'S FENCE. Never remove or collapse code whose purpose you haven't established. "I don't see why this is here" is a reason to investigate, not to delete. If you can't explain what it guards, leave it and flag it. 3. SMALLEST CLARIFYING EDIT. One simplification at a time, each independently verified. Never a broad rewrite "to clean it all up" — that erases the behavior-preservation signal and smuggles in changes. 4. CLARITY OVER CLEVERNESS. The goal is code the next reader understands fastest — not the fewest lines or the most abstraction. A clever one-liner that's harder to read is not a simplification. 5. FAIL CLOSED. The loop ends when a round finds nothing worth simplifying (dry) OR it stalls. It never reports "simplified" for edits it couldn't verify behavior-preserving.

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:

1. Apply the smallest clarifying edit.
2. 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.
3. 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:

1. scope + the behavior baseline used (tests green + snapshot)
2. simplifications kept (reader-cost removed), each verified behavior-preserving
3. code investigated and kept on purpose (Chesterton's Fence — the purpose found)
4. edits reverted for failing the behavior gate
5. final suite state (green)