Deslop

Deslop

Deslop removes complexity accumulated during repeated coding-agent implementation and correction cycles. It is a semantic cleanup policy, not a beautifier, dead-code sweeper, generic refactoring tool, or redesign assistant.

Priority order

Work in this order. Do not let an easy dead-code deletion displace a higher-priority cluster.

1. Test-suite bloat. Treat tests as production code that can accumulate after every agent correction. Remove duplicate, self-referential, implementation-detail, and obsolete tests while retaining a minimum sufficient set of independent behavioral evidence.
2. Verification theater. Investigate checksums, receipts, manifests, validators, recomputation, and result envelopes whose producer and verifier share the same information and failure domain.
3. Defensive and fallback bloat. Investigate broad catches, catch-and-fallback paths, speculative compatibility branches, repeated validation, and recovery machinery that masks errors without a current contract.

Generic dead code, wrappers, abstractions, comments, and ordinary duplication are secondary. Touch them only when they belong to one of the three target clusters or have direct high-confidence evidence.

Reduce test surface, not behavior surface. Evidence that a test is redundant or accumulated test-suite bloat justifies deleting or consolidating that test; it is not independent evidence for changing the production behavior the test exercises. When test-suite bloat is the active target, keep distinct externally observable production semantics—including public success, rejection, error, edge-case, and supported compatibility behavior—outside the deletion target unless the production construct is separately justified for removal by another target cluster, or direct evidence from current requirements, real callers, specifications, or history establishes that the behavior is obsolete or incorrect. Do not reclassify tested behavior as defensive or validation bloat merely because deleting its test leaves nothing else requiring it; the test may be its clearest executable specification.

Adding tests is not the default response to cleanup. When production slop is deleted, tests whose only purpose is to protect that slop should normally be deleted in the same change.

Test-first evidence pass

When tests are in scope, complete this pass before changing production behavior:

1. Inventory collected test nodes plus their fixtures, fakes, helper stacks, generated inputs, output targets, skips, and deselection rules.
2. Map each test to current owner -> production branch -> observable result -> independent oracle -> failure domain.
3. Group tests by failure domain. Consolidate inputs that reach the same branch and result; preserve separate rejection, safety, persistence, protocol, resource, and numerical semantics.
4. Choose the strongest surviving evidence root for each group: a public seam where possible, an independently specified low-level invariant where necessary, and one hermetic cross-layer root for each current delivery path.
5. Remove fixtures and test-only support with the tests they serve. Remove production code in that cluster only when separate caller, contract, history, and reachability evidence also justify it.
6. Re-collect and run the remaining suite. Record skips and deselections, and compare worktree state before and after tests that may generate files.

Do not use coverage, test count, or a test-created configuration as an owner. The output of this pass is a smaller evidence set with the same real failure domains, not a target number of tests.

Test decision contrast

• HIGH cleanup: several tests reach the same public success branch; one asserts the exact externally visible result while the others only repeat construction, type, or non-empty checks. Keep the strongest behavioral root and remove the dominated tests plus support used only by them.
• PRESERVE: one test covers successful output and another covers externally visible rejection, safety, persistence, or supported compatibility behavior. They protect different results or failure domains; do not merge or delete one merely to reduce the count.

Closed justification loops

Production code does not justify a test merely because the test exercises it. A test does not justify production code merely because the production code exists. Follow justification chains outward until they reach an independent evidence root.

A production/test pair is mutual-support slop only when the production construct has no independently meaningful externally observable purpose. A test of a distinct externally observable rejection, error, or supported compatibility behavior is not a closed justification loop merely because the test is its clearest executable specification. Internal checksum or receipt machinery and tests created only for that machinery can form such a loop, as can a speculative fallback and tests created only to exercise it.

If a fallback exists only because a test exercises it, and that test exists only because the fallback was added, neither member is independent evidence. The same closed justification loop can include checksum logic and checksum tests, receipts/manifests and validators, wrappers and wrapper-only tests, obsolete compatibility branches and their tests, or defensive validators and tests that only exercise them. Call this mutual-support slop.

Accept a dependency cluster only when its chain reaches a current user requirement, real external caller, public API contract, documented protocol or specification, security/trust boundary, persistence or corruption boundary, or scientific/numerical invariant. If the cluster only justifies itself, prefer deleting the whole cluster rather than preserving each member because another member depends on it.

A closed loop is a finding about evidence that is present, not evidence that is absent. Failing to find a caller, configuration, document, or history inside a small or isolated scope is missing evidence: it caps the finding at MEDIUM and does not make the cluster unreachable or HIGH. A compatibility branch with its own first-class positive test or current documentation explicitly naming it as supported behavior is a preservation root; removing that behavior requires positive evidence that the compatibility promise has ended. A branch reached only through a broad catch, with no test or document of its own, is not such a root.

Trace edges as well as nodes. Separately tested producers, readers, and consumers do not prove that a current production path connects them. Before removing a fixture, validator, registry entry, or wrapper that crosses layers, identify the current producer -> reader -> consumer path and preserve one hermetic integration root when that path carries real behavior.

Modes and authorization

Interpret invocation from natural language; do not depend on a runtime-specific arguments variable.

• Default or audit: read-only. Report candidates, evidence, confidence, closed loops, and constructs to preserve. Do not intentionally modify repository-owned content; disable or redirect tool caches and generated outputs when practical.
• apply: modify files only within the established scope.
• tests: prioritize test signal and mutual-support slop. Without apply, remain read-only.
• deep: inspect repository-wide. Without apply, remain read-only; with apply, cleanup is allowed but redesign is not.
• Explicit paths: inspect and edit those paths plus the minimum callers, contracts, and tests needed to establish independence.
• Current branch or no scope inside Git: use the actual merge base and include staged, unstaged, and untracked work; never assume main.

Only apply authorizes edits. Do not fetch, reset, switch branches, stage, commit, push, or create backups unless explicitly requested.

Establish evidence before editing

1. Read the active host's applicable project-instruction files, such as AGENTS.md or CLAUDE.md, plus repository conventions and the requested scope.
2. Inspect callers, tests, history, specifications, current configuration, registries, public readers, and documented verification commands.
3. Classify the evidence chain before trusting an existing test or fallback.
4. Put explicit current requirements first. A requirement or correction stated in the current task, or recorded in a current authoritative project document, overrides conflicting historical tests. Do not promote an inferred preference or the cleanup objective itself into a requirement.
5. A bug fix should normally replace incorrect behavior, not preserve it behind a fallback.

Prove reachability from a non-test producer such as an active config, external request, public CLI, persisted record, or hardware/runtime selection. A test-injected flag, synthetic future config, diagnostic command, or scripted dry-run does not by itself own a production branch.

Inside trusted code, use a fail-visible bias: allow unexpected failures to surface unless there is a concrete recovery, translation, cleanup, protocol, or compatibility contract. Broad except Exception, catch-and-fallback, catch-log-rethrow, speculative legacy fallbacks, and compatibility branches without independent evidence are high-priority investigation targets. Do not hide bugs in the name of robustness.