Simplifying Code#

Working rules#

• Preserve behavior, interfaces, side effects, and domain intent; prove any unshipped-shape exception has no consumers outside scope.
• Before removing a guard for an external hazard, reproduce its precondition and show the hazard is handled; otherwise retain it.
• Verify standard-library substitutions on empty, null, no-match, ordering, and zero-value cases.
• For analysis-only requests, identify targets and report proposed simplifications without editing code.

Principles#

PrincipleRulePreserve behaviorOutput must do exactly what the input did, with no silent feature additions or removals. Specifically preserve: async/sync boundaries (do not convert sync to async or reverse), error propagation paths (do not alter strategy), logging/telemetry/guards/retries that encode operational intent, and domain-specific steps (do not collapse into generic helpers that hide intent). One carve-out: a shape that existed only in an earlier iteration of the current unshipped scope is not protected behavior. Verify it has no deployed, persisted, public, external, dependent-branch, or in-repo caller outside the resolved scope, and that every required caller update fits inside the edit boundary; otherwise keep the compatibility path. This narrow exemption is about shapes with provably zero consumers; it never licenses removing a guard, which is governed by the evidence bar under AI Slop RemovalExplicit over cleverPrefer explicit variables over nested expressions. Readable beats compactSimplicity over cleanlinessPrefer straightforward code over pattern-heavy "clean" code. Three similar lines beat a premature abstractionSurgical changesTouch only what needs simplifying. Match existing style, naming conventions, and formatting of the surrounding codeSurface assumptionsBefore changing a block, identify what imports it, what it imports, and what tests cover it. Edit dependents in the same passDelete before simplifyingPrefer deletion over simplification, simplification over optimization, and optimization over automation. A pass that finds nothing to change is a valid, complete result

Changing an interface, exported name, persisted format, or path reaches past the import graph. Enumerate the producers, consumers, schemas, fixtures, generators, manifests, scripts and CI recipes, config references, and documents that carry the old identifier, and migrate them in the same pass. Close out by searching for the old identifier: zero hits, or one line accounting for each intentional remainder. Renames rot in the fixture holding the old key and the .env.example entry, neither of which any import graph contains. When the identifier is a public or exported API, Stop Conditions applies first: confirm with the user, then enumerate; the sweep runs unprompted only for internal identifiers.

Process#

1. Read first: understand the full file and its dependents before changing anything. Apply Chesterton's Fence: when code looks unnecessary but its reason is unclear, check git blame before removing it. First understand the reason, then decide if the reason still applies.
2. Identify invariants: what must stay the same? Public API, return types, side effects, error behavior. Before editing, capture relevant observable outputs from a throwaway worktree representing the exact pre-edit state; a pre-change ref suffices only if it matches that state. Preserve relevant existing uncommitted edits in the baseline copy without stashing the working tree.
3. Identify targets: find the highest-impact simplification opportunities. Impact = readability and maintainability; prioritize: control flow -> naming -> duplication -> data shaping -> types (see Smell -> Fix table)
4. Apply in order: control flow → naming → duplication → data shaping → types. Structural changes first, cosmetic last. For analysis-only requests, describe the proposed changes instead of applying them.
5. Verify: for applied changes, confirm behavior parity with relevant tests, type checks, and import checks. Compare responses, CLI output and exit status, or job artifacts against the pre-edit captures under identical inputs. Normalize only documented nondeterministic fields consistently on both sides; treat unexplained differences as regressions. Use direct comparison when tests are absent, while naming unobserved behavior. For analysis-only reports, identify the required checks and available evidence without claiming that proposed changes passed verification.
6. Pre-submit scope audit: walk every changed line and ask "does the requested task explicitly require this line?" If no, revert it and list it as a follow-up under Residual Risks. For the pre-edit complement on ambiguous-scope requests ("simplify my project"), see ia-verification-before-completion's Scope Confirmation gate.

Stop Conditions#

Stop and ask before proceeding when:

• Simplification requires changing a public API (function signatures, return types, exports)
• Behavior parity cannot be verified through tests or a direct baseline comparison
• Code is intentionally complex for domain reasons (performance-critical, protocol compliance)
• Scope implies a redesign rather than a simplification

Constraints#

• Only simplify what was requested; do not add features, expand scope, introduce new dependencies, or add speculative configurability or flexibility the request did not ask for
• Leave unchanged code untouched; do not add comments, docstrings, or type annotations to lines that were not simplified
• Do not bundle unrelated cleanups into one patch; each simplification should be a coherent, reviewable unit
• Do not introduce framework-wide patterns while simplifying a small local change
• Do not replace understandable duplication with opaque utility layers; three similar lines are better than a premature abstraction
• Keep comments that explain intent, invariants, or non-obvious constraints, and tool directives ( carve-outs). Remove comments that restate obvious code behavior. Fix stale comments only on lines this pass touches.
• If a simplification would make the code harder to understand, skip it
• Watch for over-simplification: inlining too aggressively removes names that gave concepts meaning; combining unrelated logic into one function hides distinct responsibilities; removing abstractions that exist for testability breaks the test suite
• Before deleting apparently dead code, search the whole tree, including tests, fixtures, config, templates, and string-keyed or dynamic callers. If the search cannot detect the relevant dispatch mechanism, retain the code and ask instead of treating zero hits as proof
• For artifacts whose value is self-containment (prompts, skill and agent instructions, per-service configuration, vendored policy files), duplication is cheaper than a shared dependency until edits actually drift. Extract only after coordinated changes have repeatedly gone out of sync, or a real consumer of the shared form exists

Verify#

For analysis-only reports, distinguish available evidence from checks required after implementation. Apply the following checks after code changes:

• Tests pass and types check after changes
• No behavior change (same inputs produce same outputs)
• Scope limited to requested files; no drive-by cleanups
• Match test scope to the importer count surfaced in step 1 (Surface assumptions). Zero external importers: scoped tests on the changed paths. One or more external importers, or shared/utility code edited: run tests covering each importer. Run the full suite when the test runner has no path-scoping mechanism.

Output#

For analysis-only requests, report each target's location, proposed change, rationale, behavior risk, and required verification. Label proposals as unimplemented.

After applying simplifications, report:

• Scope touched: files and functions modified
• Key simplifications: what changed and why (one line each)
• Verification: tests pass, types check, no behavior change
• Residual risks: assumptions made, areas not touched that may need attention

Task-specific references#

Read the relevant reference before implementing or reviewing the matching behavior:

• For identifying smells, removing AI-generated clutter, or eliminating a guard or workaround: simplification-patterns.md.
• When chained with other skills on a shared resolved scope: orchestrated-simplification.md.