/ia-simplifying-code

name: ia-simplifying-code
class: discipline
description: >-
  Simplifies, polishes, and declutters code without changing behavior. Use when
  asked to simplify, clean up, refactor, declutter, remove dead code or AI slop,
  or improve readability, including analysis-only simplification reports and
  code pasted inline.

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.
• Before merging parallel validators, parsers, normalizers, or default sets, run each copy on the same malformed-but-plausible and boundary inputs. Similar names or comments do not prove equivalent behavior; keep a copy separate when its callers depend on the difference.
• For analysis-only requests, identify targets and report proposed simplifications without editing code.

Principles

| Principle | Rule | |-----------|------| | **Preserve behavior** | Output 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 Removal | | **Explicit over clever** | Prefer explicit variables over nested expressions. Readable beats compact | | **Simplicity over cleanliness** | Prefer straightforward code over pattern-heavy "clean" code. Three similar lines beat a premature abstraction | | **Surgical changes** | Touch only what needs simplifying. Match existing style, naming conventions, and formatting of the surrounding code | | **Surface assumptions** | Before changing a block, identify what imports it, what it imports, and what tests cover it. Edit dependents in the same pass | | **Delete before simplifying** | Prefer 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 n