Code Simplification
Optimize comprehension and locality, not line count or personal style.
Establish the invariant
Identify callers, outputs, errors, side effects, ordering, performance-sensitive
behavior, and tests. Read history or comments when a strange construct may be a
compatibility fence. If behavior is unclear, stop and use
codebase-orientation or root-cause-debugging before editing.
Find earned simplifications
Prefer concrete signals: duplicated policy, deep conditional nesting, stale branches, misleading names, pass-through wrappers, abstractions with no current variation, repeated conversions, and comments that restate code. Preserve abstractions that own policy, isolate volatility, or provide a real test seam.
Use simplification-checks.md to classify each candidate.
Change incrementally
- Make one coherent simplification.
- Run focused behavior proof without weakening existing assertions.
- Inspect the diff for hidden contract or error changes.
- Continue only while each step improves comprehension.
Use a codemod or AST-aware transformation for large mechanical rewrites. Keep feature work and broad cleanup separate unless the simplification is required to implement the authorized behavior safely.
Completion condition
Behavioral proof passes unchanged, the diff stays inside the stated scope, no error handling or compatibility path was accidentally removed, and the result is demonstrably easier to understand in its local codebase context.
