Reducing Complexity

Reducing Complexity

> Verification status: retained, unverified-by-failure (2026-07-26, Sonnet tier, 4 runs). Offered a CSV-export task baited with future JSON/XML/delimiter needs, baseline agents shipped a single plain function and explicitly declined speculative abstraction 2/2 — and still 2/2 when escalated with "PM confirmed roadmap + tech lead suggests design it extensible now." No inducible failure at this tier; larger codebases with existing abstraction patterns to imitate remain untested.

Overview

Commitment #3 says "the simplest thing that survives reality" — this skill is its enforcement arm. Complexity is not a style problem: every layer, option, and speculative hook is surface the next bug hides behind, the next agent must re-derive, and the next change must not break. Code you didn't write is the only code with a zero defect rate.

Core principle: Complexity must be pulled in by a demonstrated need, never pushed in by an imagined one.

The Demand Test

Before adding any structural element — a layer, an interface, a config option, a generic parameter, a plugin point — name the concrete, current demand that pulls it in:

• A failing test that can't pass without it (test-driven-development).
• A second real caller that exists today.
• A named requirement from the user — not one you inferred they might have someday.

"We'll probably need it" is not demand. YAGNI is not an aesthetic; it's the observation that guesses about future needs are usually wrong, and wrong structure is harder to remove than absent structure is to add.

Simplicity Has a Floor

The commitment is the simplest thing that survives reality — not the simplest thing that demos. Reality includes: the failure path, the empty input, the concurrent caller, the hostile input where a boundary exists (threat-modeling), and the operational surface (assessing-risk's week-later failures). Cutting those isn't simplification, it's deferral with interest. The Demand Test never deletes a handled failure mode that reality has already demonstrated.

Where Complexity Hides

| Disguise | What it really is | |---|---| | "Flexible" / "configurable" | N untested code paths; every config option doubles the state space | | "Future-proof abstraction" | A guess about the future, hardened against removal | | A wrapper that only forwards | A layer of indirection with no behavior — inline it | | "Just one more special case" | The signal your model of the problem is wrong (attacking-hard-problems, change representation) | | A clever one-liner | Debug-time cost bought at write-time discount | | Dead code kept "for reference" | Version control is the reference. Delete it. | | A copy-paste-and-tweak | The third copy is where they silently diverge |

The Subtraction Pass

After GREEN, before done (verifying-before-done), spend the refactor step subtracting:

1. Delete speculative branches nothing reaches and options nothing sets.
2. Inline any indirection with exactly one caller and no behavior of its own.
3. Collapse special cases into the general case where one exists — or note that their number means the general case is mis-modeled.
4. Re-read the diff as a reviewer: every hunk should trace to the requirement. Hunks that don't are scope creep — revert them.

The tests stay green throughout; that's what they're for.

Rationalization Table

| Excuse | Reality | |---|---| | "It'll be harder to add later" | Adding structure to simple code is easy. Removing wrong structure from everything built on it is not. | | "This abstraction makes it cleaner" | Cleaner for whom? An abstraction with one implementation is indirection, not design. | | "Config option, so we don't have to decide" | An option is a decision — the decision to test and maintain both branches forever. Decide. | | "Everyone builds it this way" (layers, patterns) | Pattern catalogs describe solutions to problems you must actually have first. | | "It's already written, shame to delete it" | Sunk cost. The maintenance bill hasn't started yet — deletion is the last cheap moment. |

Quick Reference

| Situation | Move | |---|---| | About to add a layer/option/interface | Demand Test — name the current, concrete pull | | Tempted to handle a future need | Don't. Note it in one line if it's real; build when it arrives | | Wrapper with one caller, no behavior | Inline it | | Third special case appearing | Re-model instead of appending (attacking-hard-problems) | | Diff bigger than the change it delivers | Subtraction pass; revert non-tracing hunks | | Simplification would drop a failure path | Stop — that's the floor. Reality already demanded it |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kumosan2
• Source: kumosan2/Fablepowers
• License: MIT

Install and usage instructions live in the source repository linked above.