---
name: loom-code-simplification
description: "Use when working code needs behavior-preserving simplification because readability, duplication, dead code, naming, nesting, wrappers, or abstraction debt is the problem; not when behavior is still wrong."
---

# loom-code-simplification

Code simplification is a refactoring playbook for clearer code with preserved
behavior.

It grounds the current behavior, scopes the simplification, changes incrementally,
and records evidence that behavior did not change.

## Core Dependency

Use `loom-core` first. This playbook composes `loom-tickets`, `loom-evidence`,
`loom-audit`, `loom-research`, `loom-specs`, and `loom-retrospective`.

## Use This Playbook When

Use this playbook when:

- implementation is correct but unnecessarily complex
- review flags readability, duplication, dead code, or abstraction debt
- a refactor should preserve behavior exactly
- code has deep nesting, long functions, misleading names, unnecessary wrappers, or
  one-use abstractions
- simplification needs evidence before closure

Skip it when behavior is still wrong; debug or implement first.

## Route

Use this route:

```text
understand -> bound -> simplify -> verify -> record -> review
```

## Understand

Before changing code, identify:

- responsibility of the code
- callers and callees
- behavior, edge cases, side effects, ordering, and error semantics
- tests or evidence that define current behavior
- performance or platform constraints
- project conventions and nearby patterns

Use `loom-research` when historical, source, or framework context affects whether
a simplification is safe.

## Bound

Use or create a ticket when simplification is non-trivial.

Name:

- behavior to preserve
- files in scope
- files out of scope
- evidence to run before and after
- changes that require operator approval

Separate simplification from feature work and bug fixes unless the ticket
explicitly binds them.

## Simplify

Look for:

- guard clauses replacing deep nesting
- clearer names
- smaller functions with real concepts
- duplicated logic that deserves extraction
- dead code after confirming no references
- unnecessary wrappers or option layers
- redundant type assertions or conversions
- comments that restate obvious code
- one-use abstractions that hide rather than clarify

Preserve useful comments that explain constraints, ordering, compatibility,
security, or surprising behavior.

Apply one simplification cluster at a time. Stop if a change would alter behavior
or depends on unspecified behavior.

## Verify

Run checks proportional to the behavior surface:

- focused tests for touched behavior
- broader suite when refactor crosses boundaries
- type check and lint when language/tooling supports it
- manual or browser checks when UI behavior could change

Use `loom-evidence` for before/after checks when closure or audit depends on the
preservation claim.

## Review

Use `loom-audit` when simplification is broad, subtle, performance-sensitive,
security-sensitive, or easy to mistake for behavior change.

Review should check:

- behavior preservation
- diff clarity
- consistency with project patterns
- hidden coupling
- test sufficiency
- dead-code removal safety

## Done Means

The simplification pass is done when:

- behavior to preserve was named
- changes stayed inside scope
- evidence supports behavior preservation
- the result is easier to read or maintain by a concrete criterion
- ambiguous or risky removals were routed to operator, research, or audit
- reusable simplification lessons were promoted through retrospective when useful