Deslop — the pass that removes rather than adds

Every story here owes an optimization pass, and until this file existed the pass was whatever the agent felt like that afternoon. This is what one is.

The default action is deletion. A pass that ends with more lines than it started with was a refactor, and a refactor is a different piece of work with a different risk profile. "Started with" means the state immediately before THIS pass, not the branch point — a story that adds a feature adds lines, and judging the pass by the whole branch diff condemns it in advance. That number is then invisible to everyone but you, so make it recomputable: commit the story's work, then commit the pass separately. Measured: an author counting honestly from its own uncommitted draft and a reviewer counting from the branch point produced a blocking CHANGES-REQUESTED and an arbitration, with neither agent wrong on its own terms. If you cannot delete anything, say so and stop — that is a complete and respectable outcome.

The order, and why it is an order

1. Pin the behaviour BEFORE you touch anything. Run the relevant tests and keep the output. A green run after an edit proves nothing on its own: you do not know it was green before. If no test covers the area, write the narrowest one that does, and it must go red when you break the behaviour on purpose — otherwise it is not a net, it is decoration.
2. One smell class per pass, verified between passes. Dead code, then duplication, then naming and error handling, then tests. Bundling them produces a diff nobody can review and a bisect that cannot isolate the change that broke something.
3. Re-read the diff as the reviewer will. Anything in it that is not the smell you set out to remove comes back out.

What counts as slop

• Dead code — unreachable branches, unused exports, stale flags, debugging left in place, backwards-compatibility shims for something nothing calls. Verify it is unused before deleting; "I could not find a caller" and "there is no caller" are different statements and only one of them is a fact.
• Duplication that has diverged. Two copies that agree are a cost; two copies that quietly disagree are a defect.
• Pass-through wrappers and single-use helpers. Indirection that costs a jump and buys nothing. Three similar lines beat a premature abstraction — the abstraction commits you to a shape you have seen once.
• Defensive handling for states that cannot occur on a trusted internal path. It reads as care and works as camouflage: the catch that cannot fire today is the one that swallows the real error next year.
• Casts that exist to silence a type error rather than to state a truth the compiler cannot see.
• Work nobody asked for — an improvement, a rename, a docstring, a reformat on code the story never touched. It inflates the diff, hides the real change, and puts an unreviewed decision in someone else's file.
• Comments restating the line below them. Keep the comment that explains WHY, delete the one that narrates WHAT.

What is not slop, and stays

Behaviour. A guard on genuinely untrusted input. A comment carrying a reason. An abstraction with three real callers. A test that looks redundant but pins a past bug — check the history before deleting a test; the second time a bug is fixed, the deleted test is the reason.

Keep behaviour unchanged unless you are fixing a defect you can name. If the pass uncovers a real bug, that is a finding for the report and usually a separate change, not something to quietly correct inside a cleanup. The same goes for a slow data path — a query in a loop, awaits that could run together: that is code-review's data-access dimension, its fix usually adds lines, and it belongs in the self-review before this pass, not inside it.

Skill-file mode

The same instinct, applied to a SKILL.md. Run it before promoting a skill:

• Stale lines — guidance written for a version of the skill that no longer exists. Cut it.
• Bloat — detail that belongs in the caller, in a reference, or nowhere.
• Dead sentences — a line that changes nothing if deleted.
• Duplication — the same rule stated in two files, which will drift.
• Premature stop — the method ends before the work does: it asks the question but never records the answer, cleans but never verifies.
• Weak anchor — no single idea the skill turns on.
• A missing assumption — the skill does not say what has to be true for it to apply. See skill-writing.

Prose mode

For a README, a report, an error message or a commit body:

• Lead with the outcome. The first sentence is the line a reader would ask for if they said "just tell me".
• Name the number, the file, the command. "Faster" is weaker than "40s to 9s". "Fixed the config bug" is weaker than the path.
• Cut the filler — just, simply, basically, it is worth noting. If a sentence changes nothing when removed, remove it.
• No dead-end error messages. Every failure names what happened and what to do next.
• Do not achieve brevity by compressing sentences into fragments. Achieve it by dropping what the reader does not need.

The report

Files touched, what class of slop came out of each, the test output from before and after, the two line counts with the commit range a reviewer can recompute them from, and one line on what you deliberately left. The last part matters: a cleanup that silently declined to touch the worst file in the area looks identical to one that found nothing there.