Code Simplification

Purpose

code-simplification reduces code complexity while preserving exact behavior. It is not a feature workflow, not a bug fix workflow, and not permission for drive-by refactors.

The goal is code that is easier to read, review, test, and maintain with the smallest safe diff.

Same behavior.
Less cognitive load.
Fresh verification evidence.

Prefer simplifications that deepen modules instead of flattening behavior across callers. A small interface hiding real complexity is valuable; a wrapper that only moves complexity around is not.

When to Use

Use this workflow when:

• The implementation is working and relevant tests pass.
• Code review flags readability, complexity, naming, duplication, or avoidable abstraction.
• The user asks to simplify, clean up, reduce complexity, or refactor without changing behavior.
• A recently changed area has nested logic, long functions, unclear names, or repeated conditionals that make future changes risky.

Do not use this workflow when:

• Behavior must change. Use spec-driven-development, test-driven-development, or spec-evolution.
• The code is not understood well enough to preserve behavior.
• There is no verification path.
• The cleanup would touch unrelated files.
• The work is a hotfix where cleanup is not required for the fix.

Position in SDD

Preferred placement:

test-driven-development -> code-simplification -> verification-before-completion

Review feedback placement:

code-review -> receiving-code-review -> code-simplification
-> verification-before-completion

Technical-debt placement:

tech-debt identifies issue -> user approves focused cleanup
-> code-simplification

If a simplification requires changing externally visible behavior, API shape, data model, error behavior, timing, permissions, or user flow, stop and route to spec-evolution.

Preconditions

Before editing, all must be true:

• Target scope is explicit: file(s), function(s), or review finding.
• Intended behavior is known.
• Relevant tests, build, lint, typecheck, or manual verification are known.
• The current worktree state has been checked.
• The simplification is within the approved scope.

State the gate before edits:

Pre-code gate: Fast satisfied for behavior-preserving simplification of <scope>; verification: <command/check>.

For cleanup attached to an approved task:

Pre-code gate: Plan satisfied by approved Task N; simplification scope: <scope>; verification: <command/check>.

Workflow

1. Understand Before Touching

Read the smallest necessary context and answer:

• What does this code do?
• Who calls it, and what does it call?
• What inputs, outputs, errors, side effects, and ordering matter?
• Which tests or checks prove behavior?
• Does git history or nearby code explain why it exists?

If you cannot answer, do not simplify yet. Gather context or ask.

2. Identify Concrete Simplification Targets

Only act on specific signals:

Use the deletion test on wrappers, helpers, and extracted modules:

• If deleting the abstraction would force several callers to re-learn hard behavior, it is probably earning its keep.
• If deleting it mostly removes indirection and does not spread meaningful complexity, it is probably shallow.

Prefer deeper modules with clearer seams over helper sprawl.

Keep comments that explain why, tradeoffs, gotchas, or external constraints.

3. Apply One Safe Change at a Time

For each simplification:

1. Make the smallest behavior-preserving edit.
2. Run the relevant verification if cheap and available.
3. If verification fails, revert or diagnose before continuing.
4. Stop when further cleanup would broaden scope.

Do not batch unrelated simplifications. Do not modernize adjacent code just because it is nearby.

4. Verify Behavior Preservation

Use the strongest available proof:

• Unit/regression tests for pure logic.
• Integration tests for boundaries.
• Typecheck/build/lint for structural cleanup.
• Manual or visual check for UI-only simplification.
• Diff review when no automated command exists, with limits stated plainly.

Before claiming completion, use verification-before-completion.

Output Format

## Code Simplification: [Scope]

**Target:** [files/functions/review finding]
**Behavior contract:** [what must remain unchanged]
**Changes made:** [short list]
**Verification:** [commands/checks and key result]
**Verdict:** VERIFIED | PARTIAL | NOT VERIFIED | FAILED
**Limits:** [anything not checked]

Anti-Rationalizations

Stop Conditions

Stop and ask or reroute when:

• You discover the code has intentional complexity you do not understand.
• Simplification would alter behavior or public contracts.
• Tests are missing and the code is high risk.
• Cleanup would touch unrelated files.
• The diff is becoming too large to review safely.

Integration

• using-sdd routes cleanup/refactor-without-behavior-change here.
• code-review may recommend this for readability and complexity findings.
• receiving-code-review classifies review feedback before this workflow fixes it.
• tech-debt tracks broad debt; this workflow performs one focused cleanup.
• verification-before-completion is required before claiming the cleanup is complete.