SKILL.md
about 2,600 tokens- Freddie Northam
- greenline
---
name: "sweep-tests"
description: "Prune or audit a test suite with mutation proof, as its own announced task on a green suite. Invoke it by name when tests break on refactors that change no behavior, coverage is high but defects still ship, or production code carries seams only tests use."
---
# Test value sweep
Sweep tests is the start for a test suite that needs pruning or an audit. It fires by name, when tests break on refactors that change no behavior, when coverage is high but defects still ship, or when production code carries seams only tests use, and it runs on a green suite as a change of its own, never inside another change's build: propose its mode and wait, as AGENTS.md says, open its record with a `## start` section naming sweep-tests, and run the line from `frame`, the sweep itself being the change's build. Propose regular or above, since the sweep's result is reviewed by an agent other than the sweeper only where the review step runs independent; where the owner chooses quick, no review runs, and the close section names that limit. A red check goes to diagnose. It deletes nothing it has not proved by mutation, adds no test, and never certifies its own review without naming that limit.
Greenline's paths and commands for this skill stand on its references page, [references/greenline.md](references/greenline.md): read it when the work lands in the workspace.
A test must justify its presence. A test that changes when the implementation changes, while the behavior stays the same, asserts implementation. Delete it.
Then simplify the source. Seams in production code often exist only because those tests demanded them. When the test goes, the seam goes with it.
## The gate
**Run this only when the suite is green.**
A red check makes test deletion fraud, not maintenance. When a check is red, repair the source through diagnose, and restart the sweep from the top once the suite is green again. You may not touch a test at all until the suite is green again.
This skill is a separate change with its own change record. Announce it. Never run it inside another change's build.
## Prove each deletion
You may not read a test and then declare it worthless. That judgment certifies itself, and it always says yes. Run the mutation check instead.
**If the repository already has a mutation runner, use it.** Look for Stryker,
mutmut, go-mutesting, PIT, or a `test:mutation` script. Its configuration holds
knowledge this skill does not have, such as which files repay the run and which
generate thousands of worthless mutants.
**The mutation scope must cover the subject file of every test you delete in the batch.** A test whose subject sits outside the scope is never proved, however green the score looks. Widen the scope, or split the batch.
Only when the repository has none, use the tool that ships here, `bin/mutate.mjs`
in this skill's installed directory. Find it with the glob
`**/sweep-tests/bin/mutate.mjs` under the installed skills rather than assuming
a harness:
```bash
node <skill-dir>/bin/mutate.mjs --file src/thing.js --fn theFunction
```
Either tool breaks the source on purpose, one change at a time, and runs the suite after each change. A mutant that survives is a behavior that no test covers.
Validate the measurement before judging a survivor. The bundled tool masks strings and comments for its comparison and numeric operators, but its raw-text ternary operator can still swap a quoted ternary example inside a comment, and its "defect your suite ships" line is a candidate, not a diagnosis. A mutation that changes no executable behavior, or whose validity is unresolved, is an invalid measurement, not a shipped defect: the run proves no deletion, so keep the tests and seams, record the invalid measurement with the sweep's evidence, and use an already available capable runner only within the authorized scope. Never add a test for a comment, and never drop a baseline mutant to make the score pass.
A survivor inside error-handling code is the sweep's highest-value finding. Code that has not run does not work, and error handlers run rarest of all: a study of production failures in distributed data-intensive systems (Yuan et al., OSDI 2014) found 92% of catastrophic failures came from incorrect handling of non-fatal errors the software explicitly signaled. A test that exercises an error path is never pruned as redundant on coverage grounds alone; weigh its deletion against what its mutants proved.
**Take the report before you delete anything. Take it again at the end.**
Compare mutants by identity, not by number. Three failures hide behind an unchanged total:
1. **A trade.** Two mutants swap status and the total holds.
2. **A disappearance.** You removed the source a mutant lived in, so the mutant is gone. Nothing moved from killed to survived, and the behaviour is now untested. This is the one that catches seam removal.
3. **A scope change.** The second run covered fewer files than the first.
So: record every baseline mutant identifier before you start, with the source hash and the exact test command. At the end, **every baseline mutant must still exist and must still be killed.** A missing mutant fails the sweep exactly as a survived one does.
The suite stays green throughout, so green proves nothing here.
The score is not proof either. It shows that the mutants this runner generated, under this operator set, over this file set, kept their status. Behaviour no operator reaches is invisible to it, and a dynamic caller found only through a configuration string or a plugin registry is invisible to your grep. **A sweep without a score has proved nothing. A sweep with one has proved something narrow.** Say which.
Write the before-report and the after-report to different paths in the sweep change's folder. A runner that overwrites its own baseline leaves you unable to find the mutant you lost.
**A runner that reports per-test identities names one killer for each mutant:
the first test that reached it.** That is run order, not ownership. The bundled
`mutate.mjs` reports suite-level killed and survived outcomes and names no
killer; do not invent that attribution, and its silence is not evidence that a
test is redundant. A test credited with no kills can still be the only real net
under a mutant that another test happens to reach first. Use the report to
shortlist candidates. Never use it as proof. The rerun is the proof.
### Delete in batches
Time one scoped run before you plan the sweep. The cost ranges from seconds to many minutes, so whether one run for each candidate is affordable depends on the repository. When it is not, delete a batch and run once.
- The score holds. The whole batch stands.
- The score falls. One test in the batch was the only killer of a mutant. Restore the batch, halve it, and run again. Repeat until you find the test that matters, then keep it and delete the rest.
A batch proof is weaker than a proof for each test. It shows that no deletion was the unique killer of a mutant. That is enough, and it is affordable.
## Delete
- Tests that assert that a call happened, when the call is not the contract
- Tests whose assertions restate the source line above them
- Snapshot tests that you regenerate instead of read
- Tests that exercise only a mock
- Repeated coverage of one behavior across many cases
- Tests for a private function that a public function already reaches
## Keep
- The only test that covers a behavior, however ugly it is
- Call assertions on a unit whose whole job is to drive other units. There the call and its arguments are the result, and the mutation score will show it
- Regression tests that name a defect or an issue
- Contract tests at a boundary that you do not own
- Property tests and fuzz tests
## Remove the seams
A deleted test may have been the only caller of a seam. Grep for each one.
- An interface with one implementation
- A constructor parameter that only a test supplies
- An exported symbol that only tests import
- A mock or fake, and the hook it plugs into
- A flag that only a test reads
Delete the seam, or inline it. Follow each simplification to its end. When you remove a seam and a wrapper becomes a pass-through, remove the wrapper too.
**A seam can have one caller, and that caller can be a test in another file. Leave that seam alone.** Report it as a candidate for a later sweep. A sweep that reaches past its own scope breaks files that nobody asked you to touch.
**A grep does not find every caller.** Dependency injection tokens, plugin
registries, configuration strings and generated registrations all reference a
symbol without naming it in a way `rg` matches. Removing such a seam keeps every
unit test green, removes the mutants that lived in it, and fails in production.
When a symbol is exported across a package boundary, treat the grep as
inconclusive and leave it.
## Report
Close with the two scores and one table.
```
Tests: 26 -> 9 (-65%) Mutation score: 16/18 -> 16/18 (no change)
```
The table lists each test you deleted and each seam you removed. Prose is not the report.
The baselines, the identified survivors and kills, both reports, the table and the resulting checks stay with the sweep's change in its folder, and acceptance is judged against those measurements: an aggregate score alone cannot prove that each baseline mutant remains killed. The sweep is implementation work. Commit its result with the change's trailer for its review step, like any build; no review runs only where the owner chose quick, and the close section names that limit.
## Don't
- Delete a test to turn a red check green
- Delete a test that you did not prove by mutation
- Rewrite a test and count that as a sweep
- Add a test in this pass
- Change anything outside the test suite and its seams
## It's working if
- Every deletion has a mutation report before it and one after it.
- Both reports name the same mutants, not just the same total.
- The close is two scores and a table. Prose is not the report.
- Seams disappear in the same pass as the tests that demanded them.
- A sweep that cannot prove a deletion says so, and keeps the test.
- You deleted nothing while a check showed red.
## Handoff
Consumes: a green suite and the request to sweep it Produces: the before and after mutation results at different paths, the deletion and seam table, and the baselines and kills, in the change's folder under .greenline/ledger/<id>/; the sweep committed as the change's build Next: frame, under the mode the owner approves; the sweep is the change's build, and review and verify follow at the depths its mode gives
SKILL.md as installed, byte for byte SHA-256 209f16cc910bab9d7444aef734c9e6d6f344c47b211c6d819590ef4debafcb15