Repository context. Gather first
Collect each with its own Bash call:
- Current branch,
git branch --show-current
- Default branch,
git symbolic-ref --short refs/remotes/origin/HEAD (unset: ask, unless the
user named it)
- Working tree status (empty = clean),
git status --porcelain | head -20
Arguments
$ARGUMENTS: <folder> (required, one folder per batch; the repository root runs the
Repository plan instead of the steps), --max <n> (the recording run's mutant
cap, default 100), --flaky <test> (repeatable; flaky tests the user names, also taken from the
conversation), --cannot-fail-only (run Cannot-fail-only mode instead of
steps 1 to 6). No folder: run the plan when the user asked for the whole repository, otherwise ask
for one.
Working files
Every step reads and writes <work> = .work/testing-cleanup/<folder-slug>/ in the repository
root, <folder-slug> being the folder path lowercased with every character outside [a-z0-9._-]
replaced by -. It holds before.tsv and after.tsv (the mutant records), classifier-brief.md,
classifier-answer.md (in cannot-fail-only mode, skeptic-brief-<n>.md and
skeptic-answer-<n>.md instead), decisions.md (the decision table, each item's approval state,
the step reached, and each edited file's git hash-object after its last edit) and pr-body.md.
Right after each edit to a test file (the step 2 quarantine, each rewrite, deletion or merge in
step 5 or cannot-fail-only step 4, each revert the user makes in step 6), run
git hash-object "<path>" and record the hash and the step reached in decisions.md; step 0's
resume check reads them.
Read the working files from that path at every step, never from conversation memory, so a
compacted or resumed session continues where the files say it stopped. Before the first write,
confirm .work/ is ignored (git check-ignore -q .work/x); when it is not, create
.work/.gitignore holding *, and say so.
Repository plan
For the repository root (git rev-parse --show-toplevel), plan one batch per test project, then
run each through the single-folder steps below. The plan edits and runs no test. Its files live in
.work/testing-cleanup-plan/, read at every batch boundary, never from conversation memory.
- Findings. Run the step 1 scanner command once with
CANT_FAIL_SCAN_ROOT set to the
repository root, and save its table as findings.md there.
- Batches. Group the rows by folder: a row whose
project: names a .csproj belongs to that
file's directory; any other row to its own file's directory. A folder inside another listed
folder of the same language (the adapters' language, as step 0 reads it) joins that folder's
batch, since a batch scans its whole folder; one holding a folder of another language is marked
skip: mixed languages, which step 0 would refuse. The repository root is never a batch: list
its own rows as not planned. A project with no finding gets no batch. Mark a batch
skip: kind <kind> when any of its rows has kind live or operational.
- Show. Write
plan.md there, one row per batch ordered by finding count, most first:
folder, findings, kind, ci, state (pending, skip: <reason>, then the outcome). Show it,
ask whether any unknown-kind batch's tests reach live or shared environments (outside C#,
every kind is unknown), mark each one the user names skip: kind live, and ask which
batches to run; the default is every pending row in order. A skip: kind batch runs only
when the user names its folder, and then only in
Cannot-fail-only mode: never run a live or operational project's
tests, a baseline included.
- Run. Run steps 0 to 7 on each chosen folder in turn, unchanged, with the invocation's
--max and --cannot-fail-only and the --flaky tests under that folder: each batch has its
own <work>, diff and per-item approvals. The next batch starts only after step 7 commits
this one, since step 0 refuses a dirty tree. Record each outcome in plan.md; a batch
that stops records why, and the plan goes on only on the user's yes. Unattended, run only the first pending batch whose kind
is not unknown.
Steps
0. Refuse
Stop, naming the remedy, when any of these holds; check them all before step 1:
- The current branch is the default branch, or the working tree is dirty. Cleanup stages a batch
that must be reviewable as one diff. A resumed batch is the exception: when
<work>/decisions.md
exists and every changed path's git hash-object "<path>" equals the hash it recorded for that
path after its last edit, continue at the step it records, in cannot-fail-only mode when
decisions.md holds the mode: cannot-fail-only line. A path with a different hash carries
an edit the batch did not make: refuse.
- The
mutation-testing plugin is not enabled; the mutation gate needs it.
mutation-testing has no config for the repository, or its test-command is missing or lacks a
standalone, unquoted {tests} word: both mutation runs use it. Point to
/mutation-testing:setup apply.
- The folder does not exist, or
/testing:audit --file <path> claims no file under it.
- The folder holds test files of more than one language (the adapters'
language), such as a
*.test.sh harness beside Python tests. The one test-command cannot run them all, so the
baseline would be red. Name a subfolder per language and ask for one.
The two mutation-testing checks and the language check guard the mutation runs only; they do not
apply under --cannot-fail-only. When every check that holds is one of those three, at least one
being a mutation-testing check, and --cannot-fail-only was not given, name each remedy, then offer
Cannot-fail-only mode and continue in it only on the user's yes.
Unattended, or on a no, stop.
1. Inputs
Gather all four before any edit, and write the candidate list to decisions.md:
- The scanner's findings over the folder:
env CANT_FAIL_SCAN_ROOT="<absolute folder>" bash "${CLAUDE_PLUGIN_ROOT}/skills/audit/scripts/cant-fail-scan.sh" --findings.
Quote every path in a command, each as its own argument. Every row is a candidate, report-only
rules included. Location is repo-relative.
- Judge-pass findings, when
/testing:audit --judge --persist-findings wrote any. Read every
.work/reviews/*/*.md whose frontmatter has type: review-findings and a branch: equal to
the current branch exactly (the frontmatter, not the directory, proves the branch), and keep
the testing/judge/rule-restated-expectation rows whose Location is under the folder. A FLAG
makes its test a candidate; a PASS clears no scanner finding.
- The tests the user names as flaky; cleanup detects no flakiness. For each, ask for an owner and
a tracking issue, which step 2 writes into the reason; cleanup files no issue.
- The tests the user names as suspected duplicates or layer replays (a suite that re-proves,
through a mock, what a stronger suite already proves).
mock-only-oracle rows from input 1 are
where layer replays usually surface.
Then sweep the folder's existing quarantines: grep -rn -- "test-change: quarantined" "<folder>".
A quarantine whose date is today or earlier is expired. List each expired one in decisions.md
with its owner and tracking issue (none when its reason has neither), and ask the user, per
item, to re-enable it (step 2 removes the skip) or escalate it (the skip stays, and the report
names the owner and issue that must act). Renew a date only on the user's yes, writing the new
date and why into the reason. Never re-enable, renew or delete a quarantine on your own;
unattended, list the expired ones and change none.
No candidate and no expired quarantine: report nothing to clean in <folder> and stop.
2. Quarantine
Skip each named flaky test with the framework's own skip form, the test_skip or body_skip
vocabulary of the adapter that claims its file (${CLAUDE_PLUGIN_ROOT}/skills/audit/adapters/),
with the reason test-change: quarantined <YYYY-MM-DD>: flaky, <evidence>, owner <who>, tracked <issue>. The date, 7 days out, is the expiry the step 1 sweep reads. Write none for an owner or
issue the user did not give, and report that quarantine as untracked. The test-change: prefix is
the marker the test-weaken hook accepts, so the edit is not denied under
test-weaken-block: error. For each expired quarantine the user chose to re-enable, remove the
skip and leave a test-change: quarantine lifted <YYYY-MM-DD>, tracked <issue> comment at the
edit; a re-enabled test that still fails turns step 3's baseline red. Quarantine comes first so
both mutation runs skip these tests.
A quarantine keeps a flaky test off the blocking path while an owner tracks it to a fix; a skip
with no owner or expiry turns it off for good. Basis, MEDIUM (two independent
primaries): Google's auto-quarantine files a bug
(Flaky Tests at Google,
2016, Google's internal CI; the post also warns quarantine can mask a real race condition), and
Azure Pipelines pairs suppression with a bug and resets the flag when it resolves
(flaky test management).
As of 2026-10-06. Recheck trigger: Google publishes a successor flaky-test post, or the Azure
page's update date changes.
3. Record the baseline
Invoke /mutation-testing:audit --exercised <folder> --max <n> --record-mutants <work>/before.tsv
through the Skill tool, with no --paths. Then read its report:
- A red baseline stops the batch. List the failing tests so the user can name the flaky ones for
step 2 or fix them; quarantine nothing on your own. A test that fails the same way every run is
not flaky: report it as a possible product bug whose fix is its own change, never a quarantine.
K0 empty, no mapping: scope empty, or a refusal after the user declines both the audit's
install command and its tool: manual offer: the gated batch stops, since nothing the tests
kill can be gated. Name the result, then offer Cannot-fail-only mode
and continue in it only on the user's yes, keeping the step 2 quarantines in the batch.
Unattended, or on a no, stop.
- Mutants dropped by the cap: state how many, and continue only on the user's yes or with a larger
--max.
4. Classify
Write <work>/classifier-brief.md from context/classifier-brief.md,
with <plugin-root> rendered as ${CLAUDE_PLUGIN_ROOT}, and dispatch a fresh-context
general-purpose subagent with model: opus (for the cases where that alias resolves to the
session's own model, see
sub-agents: choose a model, as of
2026-10-31; recheck when that section changes those cases). Opus, not the judge pass's default
sonnet, because a wrong deletion costs more than a wrong verdict. Write its table to
<work>/classifier-answer.md and apply that file's reading rules.
Every brief this skill writes keeps the rendered plugin root, with no resolver or fallback path,
relying on how the harness retires a plugin's superseded version directory after an update.
This skill relies on the per-call model it passes taking effect; how that ranks against the
agent's frontmatter and operator overrides is set by
https://code.claude.com/docs/en/sub-agents#choose-a-model. As of 2026-10-02. Recheck when that
section changes the order.
5. Apply
Fill decisions.md with one row per candidate: test, row, evidence, K citation or no-contract
statement, action, gate-blind, approved-by.
- Rows 2 and 3: apply the rewrite in the working tree. A judge-proposed diff is applied only through
a row 2 or 3 the classifier picked.
- Rows 4 and 5: list each deletion and merge with its reason and apply it only after the user says
yes to that item. A row 4 whose logic lives in a collaborator gets that test in the same batch.
- A file whose adapter has
block_model: file (bash-harness) is rewrite-only: never delete or
merge it, or checks inside it.
- When
bash "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-config.sh" prints rules.test-weaken-block
error, each deletion carries a test-change: cleanup row <n>: <reason> comment at the edit.
- Gate-blind: a changed or deleted test none of whose production files holds a
before.tsv row is
marked gate-blind and needs the user's yes, even for a rewrite. A test's production files are
the files defining the code it reaches: what it calls directly, through a helper, an interface
or dependency injection, read from the code. Read the calls, not the imports: a C# using names
a namespace, never a file, and a test in a child namespace of its subject needs no using.
Unattended, apply only the row 2 and 3 rewrites that are not gate-blind, and leave every yes-gated
item listed and unapplied.
6. Gate
First re-scan each file the batch rewrote with the step 1 command plus --file "<path>". A finding
step 1 did not list is a rewrite that cannot fail or checks little (a weak oracle, a recomputed
expectation): the batch stops and names it until the rewrite is repaired. The re-scan sees only
the scanner's rules; the judgment-only shapes in test-value §5 stay with each rewrite's row
review.
Then invoke /mutation-testing:audit --exercised <folder> --replay-mutants <work>/before.tsv --record-mutants <work>/after.tsv through the Skill tool and read its Gate: line. The replay
reapplies each before.tsv mutant and compares the records mutant by mutant: one detected before
and not after is newly surviving.
- A red replay baseline (a changed test fails on unmutated code) stops the batch and names the
failing tests.
Gate: block: the batch stops. For each newly-surviving <path>:<line> <operator> line, list the
candidate changes: the batch's changed tests whose production files (step 5) include <path>,
or every changed test when none does, since each mutant ran against the whole test set. The
user reverts the ones they choose; then replay again. Cleanup reverts nothing itself.
Gate: pass: go on.
- Any other outcome (no
Gate: line, a refusal, a compare that could not run) stops the batch.
Only Gate: pass reaches step 7.
7. Report and commit
Write the decision table and the gate result (K0 and K1, each newly surviving mutant with its
triage) to <work>/pr-body.md, and the findings file to the branch's findings directory,
.work/reviews/<branch-slug>/<YYYYMMDDTHHMMSSZ>-testing-cleanup.md, the slug and home as
/review:fanout "Shared inputs" defines them. One row per candidate that a rule selected, in the
shape plugins/review/reference/findings-file-shape.md gives: Tier and Confidence copied from
the source row, Surface(s) testing:cleanup, Finding the source row's Finding (rule id and
threshold first) followed by cleanup row <n>: <action>, Action reading
applied by /testing:cleanup in this branch; review, do not re-apply (or kept: <reason>). Quarantined tests have no rule and appear in
pr-body.md only, each with its expiry, owner and tracking issue, beside each expired quarantine
and the user's choice for it (re-enabled, escalated, renewed to a date, or undecided).
Show the batch. While a yes-gated item is still unanswered, stop there and list it. Otherwise
commit the batch's files only (named paths, never git add -A) without waiting for a
batch-level approval: every yes-gated item in it already had the user's answer, and the commit
is local. Report the commit's SHA and how to undo it (while it is the branch's latest commit,
git reset --soft HEAD~1 drops it and keeps its changes staged; later, git revert <sha>),
then delete before.tsv and after.tsv. Push and open the pull request only when the user
asks, through /source-control:pull-request when that plugin is enabled. Unattended runs stop
before the commit.
Cannot-fail-only mode
For a folder no usable mutation tool can gate. Deleting a test that cannot fail loses no kill a
mutation run could record, so this mode deletes only such tests and needs no gate. It runs no test
and no mutation tool, so it is safe on suites whose tests reach live systems. It proposes no
quarantine, rewrite or merge. Step 0's branch, tree and folder checks still apply;
these steps replace steps 1 to 6, and step 7 follows unchanged.
- Candidates. Write
mode: cannot-fail-only to decisions.md, and record each step reached
as cannot-fail-only <n>. Run the step 1 scanner command and quarantine sweep, and record the
scanner's test blocks parsed count in decisions.md. An in-scope row is one whose rule is
rule-zero-assertion, rule-recomputed-expectation or rule-inert-assertion (section 5 of
${CLAUDE_PLUGIN_ROOT}/skills/test-value/SKILL.md says what each means). The last two flag one
statement, so a test is a candidate only when it has no assertion at all or every assertion in
it is an in-scope row; a test with any other assertion is not in this mode. Every other row is
out of scope, rule-conditional-assertion included (its assertion runs, and can fail, when the
branch is taken), as are judge verdicts and tests the user names as flaky or duplicate: list each in decisions.md as not in this mode and leave it. So is a test in a
block_model: file adapter's file, and a test holding a catch ... when (...) guard, such as a
trial-license check: neither is deleted or edited. List expired quarantines found by the sweep,
and change none. No candidate: report nothing to clean in <folder> and stop, unless step 2
quarantined or re-enabled a test in this batch; then go to step 7 with those alone.
- Skeptic. Per test file holding a candidate, write
<work>/skeptic-brief-<n>.md from
context/skeptic-brief.md, with <plugin-root> rendered as
${CLAUDE_PLUGIN_ROOT}, and dispatch a fresh-context general-purpose subagent with
model: opus, for the reason step 4 (Classify) gives. Write its table to
<work>/skeptic-answer-<n>.md and apply that file's reading rules: only a cleared row is a
deletion candidate. Before the first skeptic, run
bash "${CLAUDE_PLUGIN_ROOT}/lib/read-verification.sh" --plugin testing --skill cleanup --file docs/conventions/testing.yaml and copy
its line into decisions.md (levels);
standard and strict are this step as written. Under light, and off, which acts as light
here, dispatch no skeptic and never clear a candidate in this context instead: each row's skeptic
verdict reads verification: skipped (<level>), no row is cleared, and this mode deletes nothing.
- Propose. Fill
decisions.md with one row per candidate: test, rule, quoted line, skeptic
verdict, action, approved-by. A cleared row is a row 4 deletion whose no-contract statement is
the skeptic's reason, unless a reference it quotes as naming a symbol elsewhere lies inside
another cleared test: skeptics run per file, so two candidates can each be the other's only
witness. That row is keep: compile-time reference only in another candidate (<file:line>).
Any other row is keep; when the skeptic names a statement that can throw, the action reads keep: throw is the only oracle (<file:line>), which a gated run or a
cant-fail-ok: <why> annotation can settle later.
- Delete. Apply each deletion only after the user's yes to that item; unattended, apply none.
Remove the whole test (its attributes, decorators and doc comment) and an import only it used,
and nothing else: a helper or field the test alone used stays, for
/code-tidying:audit-dead-code. Keep the file's line endings: a file whose every line ended in
CRLF before the edit
(grep -c $'\r$' -- "<path>" equals wc -l < "<path>") still does after it. The
test-change: cleanup row 4: <reason> comment rule of step 5 applies.
- Check. Re-run the scanner over the folder. Its
test blocks parsed count must be the count
decisions.md recorded in step 1 minus the approved deletions, and git status --porcelain
must list only files under the folder. Any other result stops the batch and names the difference.
Step 7's report states that the batch ran in this mode, which step 0 check or step 3 result led to
it, if any, and that no mutation gate ran; it has no K1, and no K0 beyond that step 3 result.
Every deletion here is gate-blind by construction. It also states that nothing was built or
linted: a helper the deleted test alone used can trip an unused-code check, so ask the user to
build and lint the test project before pushing the batch.
What this skill does NOT do
- Commit a batch before showing it, while a yes-gated item is unanswered, or in an unattended
run; push it unasked; or delete, merge or revert any test without a yes on that item.
- Detect flaky tests, sweep quarantines outside the named folder, file a tracking issue, or bisect
a lost kill.
- Clean more than one folder in one batch (a repository plan runs each folder as its own batch),
or turn the
test-weaken hook off.
Next
- Open the batch's pull request with
pr-body.md as its body: /source-control:pull-request create
- A deletion left an export, global or wrapper with no production caller: /code-tidying:audit-dead-code
Gotchas
- The gate is necessary, not sufficient. A replay that passes says no recorded kill was lost.
It says nothing about behavior no mutant reached, so every deletion still needs its row 4 or 5
reason and the user's yes.
- "No caller found" is not a no-contract statement. A contract reached through dependency
injection, reflection or an HTTP route does not show up in a search; that test is rewritten or
kept.
- The gate compares sets, not tests. A weakened test passes the gate when another changed test
in the batch now kills the same mutants. Each rewrite is still reviewed on its own row; per-test
kill attribution is not built.
- Cleanup never edits production code. The replay refuses when production changes, so an export
whose only caller was a deleted test stays until a separate dead-code pass removes it.
- In cannot-fail-only mode the skeptic is the only check. A test with no assertion still fails
when its setup throws: a constructor, a dependency-injection resolution, a fixture. On one large
.NET suite, skeptics rejected 3 of 42 proposed deletions for that reason.
- A record outlives nothing. Production code that changes between the two runs makes the replay
refuse. Finish a batch before rebasing it.
1---2name: cleanup3description: "Clean up low-value tests in one folder, or plan a repo as per-project batches: reads /testing:audit findings, its judge pass's FLAG verdicts and the tests the user names as flaky, has a fresh-context classifier pick quarantine, rewrite, delete, merge or keep per test, rewrites by default, and deletes or merges only with a stated no-contract reason and the user's yes on each item. A mutation gate records the mutants the tests kill before any edit and replays them after, blocking the batch when a kill is lost. An attended run commits the batch once it is shown; an unattended one does not. Use when: the user wants an existing suite of tautological, vacuous or low-value tests cleaned up ('clean up these tests', 'prune the useless tests in this folder', 'clean up the whole repo's tests', 'fix the tests audit flagged'), or audit findings need acting on rather than reporting. Needs the mutation-testing plugin set up, or --cannot-fail-only, which deletes only skeptic-cleared tests that cannot fail."4argument-hint: "<folder|repo root> [--max <n>] [--flaky <test> ...] [--cannot-fail-only]"5user-invocable: true6disable-model-invocation: false7metadata:8 source: https://skillmd.com/skills/melodic-software/cleanup9 workflow-stage: test10 summary: Rewrite, quarantine or delete low-value tests behind a mutation gate, or delete cannot-fail ones11---1213## Repository context. Gather first1415Collect each with its own Bash call:1617- Current branch, `git branch --show-current`18- Default branch, `git symbolic-ref --short refs/remotes/origin/HEAD` (unset: ask, unless the19 user named it)20- Working tree status (empty = clean), `git status --porcelain | head -20`2122## Arguments2324`$ARGUMENTS`: `<folder>` (required, one folder per batch; the repository root runs the25[Repository plan](#repository-plan) instead of the steps), `--max <n>` (the recording run's mutant26cap, default 100), `--flaky <test>` (repeatable; flaky tests the user names, also taken from the27conversation), `--cannot-fail-only` (run [Cannot-fail-only mode](#cannot-fail-only-mode) instead of28steps 1 to 6). No folder: run the plan when the user asked for the whole repository, otherwise ask29for one.3031## Working files3233Every step reads and writes `<work>` = `.work/testing-cleanup/<folder-slug>/` in the repository34root, `<folder-slug>` being the folder path lowercased with every character outside `[a-z0-9._-]`35replaced by `-`. It holds `before.tsv` and `after.tsv` (the mutant records), `classifier-brief.md`,36`classifier-answer.md` (in cannot-fail-only mode, `skeptic-brief-<n>.md` and37`skeptic-answer-<n>.md` instead), `decisions.md` (the decision table, each item's approval state,38the step reached, and each edited file's `git hash-object` after its last edit) and `pr-body.md`.39Right after each edit to a test file (the step 2 quarantine, each rewrite, deletion or merge in40step 5 or cannot-fail-only step 4, each revert the user makes in step 6), run41`git hash-object "<path>"` and record the hash and the step reached in `decisions.md`; step 0's42resume check reads them.4344Read the working files from that path at every step, never from conversation memory, so a45compacted or resumed session continues where the files say it stopped. Before the first write,46confirm `.work/` is ignored (`git check-ignore -q .work/x`); when it is not, create47`.work/.gitignore` holding `*`, and say so.4849## Repository plan5051For the repository root (`git rev-parse --show-toplevel`), plan one batch per test project, then52run each through the single-folder steps below. The plan edits and runs no test. Its files live in53`.work/testing-cleanup-plan/`, read at every batch boundary, never from conversation memory.54551. **Findings.** Run the step 1 scanner command once with `CANT_FAIL_SCAN_ROOT` set to the56 repository root, and save its table as `findings.md` there.572. **Batches.** Group the rows by folder: a row whose `project:` names a `.csproj` belongs to that58 file's directory; any other row to its own file's directory. A folder inside another listed59 folder of the same language (the adapters' `language`, as step 0 reads it) joins that folder's60 batch, since a batch scans its whole folder; one holding a folder of another language is marked61 `skip: mixed languages`, which step 0 would refuse. The repository root is never a batch: list62 its own rows as `not planned`. A project with no finding gets no batch. Mark a batch63 `skip: kind <kind>` when any of its rows has kind `live` or `operational`.643. **Show.** Write `plan.md` there, one row per batch ordered by finding count, most first:65 folder, findings, kind, ci, state (`pending`, `skip: <reason>`, then the outcome). Show it,66 ask whether any `unknown`-kind batch's tests reach live or shared environments (outside C#,67 every kind is `unknown`), mark each one the user names `skip: kind live`, and ask which68 batches to run; the default is every `pending` row in order. A `skip: kind` batch runs only69 when the user names its folder, and then only in70 [Cannot-fail-only mode](#cannot-fail-only-mode): never run a live or operational project's71 tests, a baseline included.724. **Run.** Run steps 0 to 7 on each chosen folder in turn, unchanged, with the invocation's73 `--max` and `--cannot-fail-only` and the `--flaky` tests under that folder: each batch has its74 own `<work>`, diff and per-item approvals. The next batch starts only after step 7 commits75 this one, since step 0 refuses a dirty tree. Record each outcome in `plan.md`; a batch76 that stops records why, and the plan goes on only on the user's yes. Unattended, run only the first `pending` batch whose kind77 is not `unknown`.7879## Steps8081### 0. Refuse8283Stop, naming the remedy, when any of these holds; check them all before step 1:8485- The current branch is the default branch, or the working tree is dirty. Cleanup stages a batch86 that must be reviewable as one diff. A resumed batch is the exception: when `<work>/decisions.md`87 exists and every changed path's `git hash-object "<path>"` equals the hash it recorded for that88 path after its last edit, continue at the step it records, in cannot-fail-only mode when89 `decisions.md` holds the `mode: cannot-fail-only` line. A path with a different hash carries90 an edit the batch did not make: refuse.91- The `mutation-testing` plugin is not enabled; the mutation gate needs it.92- `mutation-testing` has no config for the repository, or its `test-command` is missing or lacks a93 standalone, unquoted `{tests}` word: both mutation runs use it. Point to94 `/mutation-testing:setup apply`.95- The folder does not exist, or `/testing:audit --file <path>` claims no file under it.96- The folder holds test files of more than one language (the adapters' `language`), such as a97 `*.test.sh` harness beside Python tests. The one `test-command` cannot run them all, so the98 baseline would be red. Name a subfolder per language and ask for one.99100The two `mutation-testing` checks and the language check guard the mutation runs only; they do not101apply under `--cannot-fail-only`. When every check that holds is one of those three, at least one102being a `mutation-testing` check, and `--cannot-fail-only` was not given, name each remedy, then offer103[Cannot-fail-only mode](#cannot-fail-only-mode) and continue in it only on the user's yes.104Unattended, or on a no, stop.105106### 1. Inputs107108Gather all four before any edit, and write the candidate list to `decisions.md`:1091101. The scanner's findings over the folder:111 `env CANT_FAIL_SCAN_ROOT="<absolute folder>" bash "${CLAUDE_PLUGIN_ROOT}/skills/audit/scripts/cant-fail-scan.sh" --findings`.112 Quote every path in a command, each as its own argument. Every row is a candidate, report-only113 rules included. `Location` is repo-relative.1142. Judge-pass findings, when `/testing:audit --judge --persist-findings` wrote any. Read every115 `.work/reviews/*/*.md` whose frontmatter has `type: review-findings` and a `branch:` equal to116 the current branch exactly (the frontmatter, not the directory, proves the branch), and keep117 the `testing/judge/rule-restated-expectation` rows whose `Location` is under the folder. A FLAG118 makes its test a candidate; a PASS clears no scanner finding.1193. The tests the user names as flaky; cleanup detects no flakiness. For each, ask for an owner and120 a tracking issue, which step 2 writes into the reason; cleanup files no issue.1214. The tests the user names as suspected duplicates or layer replays (a suite that re-proves,122 through a mock, what a stronger suite already proves). `mock-only-oracle` rows from input 1 are123 where layer replays usually surface.124125Then sweep the folder's existing quarantines: `grep -rn -- "test-change: quarantined" "<folder>"`.126A quarantine whose date is today or earlier is expired. List each expired one in `decisions.md`127with its owner and tracking issue (`none` when its reason has neither), and ask the user, per128item, to re-enable it (step 2 removes the skip) or escalate it (the skip stays, and the report129names the owner and issue that must act). Renew a date only on the user's yes, writing the new130date and why into the reason. Never re-enable, renew or delete a quarantine on your own;131unattended, list the expired ones and change none.132133No candidate and no expired quarantine: report `nothing to clean in <folder>` and stop.134135### 2. Quarantine136137Skip each named flaky test with the framework's own skip form, the `test_skip` or `body_skip`138vocabulary of the adapter that claims its file (`${CLAUDE_PLUGIN_ROOT}/skills/audit/adapters/`),139with the reason `test-change: quarantined <YYYY-MM-DD>: flaky, <evidence>, owner <who>, tracked140<issue>`. The date, 7 days out, is the expiry the step 1 sweep reads. Write `none` for an owner or141issue the user did not give, and report that quarantine as untracked. The `test-change:` prefix is142the marker the `test-weaken` hook accepts, so the edit is not denied under143`test-weaken-block: error`. For each expired quarantine the user chose to re-enable, remove the144skip and leave a `test-change: quarantine lifted <YYYY-MM-DD>, tracked <issue>` comment at the145edit; a re-enabled test that still fails turns step 3's baseline red. Quarantine comes first so146both mutation runs skip these tests.147148A quarantine keeps a flaky test off the blocking path while an owner tracks it to a fix; a skip149with no owner or expiry turns it off for good. Basis, MEDIUM (two independent150primaries): Google's auto-quarantine files a bug151([Flaky Tests at Google](https://testing.googleblog.com/2016/05/flaky-tests-at-google-and-how-we.html),1522016, Google's internal CI; the post also warns quarantine can mask a real race condition), and153Azure Pipelines pairs suppression with a bug and resets the flag when it resolves154([flaky test management](https://learn.microsoft.com/en-us/azure/devops/pipelines/test/flaky-test-management)).155As of 2026-10-06. Recheck trigger: Google publishes a successor flaky-test post, or the Azure156page's update date changes.157158### 3. Record the baseline159160Invoke `/mutation-testing:audit --exercised <folder> --max <n> --record-mutants <work>/before.tsv`161through the Skill tool, with no `--paths`. Then read its report:162163- A red baseline stops the batch. List the failing tests so the user can name the flaky ones for164 step 2 or fix them; quarantine nothing on your own. A test that fails the same way every run is165 not flaky: report it as a possible product bug whose fix is its own change, never a quarantine.166- `K0 empty`, `no mapping: scope empty`, or a refusal after the user declines both the audit's167 install command and its `tool: manual` offer: the gated batch stops, since nothing the tests168 kill can be gated. Name the result, then offer [Cannot-fail-only mode](#cannot-fail-only-mode)169 and continue in it only on the user's yes, keeping the step 2 quarantines in the batch.170 Unattended, or on a no, stop.171- Mutants dropped by the cap: state how many, and continue only on the user's yes or with a larger172 `--max`.173174### 4. Classify175176Write `<work>/classifier-brief.md` from [`context/classifier-brief.md`](context/classifier-brief.md),177with `<plugin-root>` rendered as `${CLAUDE_PLUGIN_ROOT}`, and dispatch a fresh-context178`general-purpose` subagent with `model: opus` (for the cases where that alias resolves to the179session's own model, see180[sub-agents: choose a model](https://code.claude.com/docs/en/sub-agents#choose-a-model), as of1812026-10-31; recheck when that section changes those cases). Opus, not the judge pass's default182`sonnet`, because a wrong deletion costs more than a wrong verdict. Write its table to183`<work>/classifier-answer.md` and apply that file's reading rules.184185Every brief this skill writes keeps the rendered plugin root, with no resolver or fallback path,186relying on how the harness retires a plugin's superseded version directory after an update.187188- **Pointer**: when deciding whether a rendered plugin root can still be relied on, fetch189 <https://code.claude.com/docs/en/plugins/loading#cleanup-of-previous-versions> live.190- **As of**: 2026-10-13 (Claude Code 2.1.296)191- **Recheck trigger**: a Claude Code release note or that docs section changes plugin cache cleanup.192193This skill relies on the per-call `model` it passes taking effect; how that ranks against the194agent's frontmatter and operator overrides is set by195<https://code.claude.com/docs/en/sub-agents#choose-a-model>. As of 2026-10-02. Recheck when that196section changes the order.197198### 5. Apply199200Fill `decisions.md` with one row per candidate: test, row, evidence, K citation or no-contract201statement, action, gate-blind, approved-by.202203- Rows 2 and 3: apply the rewrite in the working tree. A judge-proposed diff is applied only through204 a row 2 or 3 the classifier picked.205- Rows 4 and 5: list each deletion and merge with its reason and apply it only after the user says206 yes to that item. A row 4 whose logic lives in a collaborator gets that test in the same batch.207- A file whose adapter has `block_model: file` (`bash-harness`) is rewrite-only: never delete or208 merge it, or checks inside it.209- When `bash "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-config.sh"` prints `rules.test-weaken-block`210 `error`, each deletion carries a `test-change: cleanup row <n>: <reason>` comment at the edit.211- Gate-blind: a changed or deleted test none of whose production files holds a `before.tsv` row is212 marked gate-blind and needs the user's yes, even for a rewrite. A test's production files are213 the files defining the code it reaches: what it calls directly, through a helper, an interface214 or dependency injection, read from the code. Read the calls, not the imports: a C# `using` names215 a namespace, never a file, and a test in a child namespace of its subject needs no `using`.216217Unattended, apply only the row 2 and 3 rewrites that are not gate-blind, and leave every yes-gated218item listed and unapplied.219220### 6. Gate221222First re-scan each file the batch rewrote with the step 1 command plus `--file "<path>"`. A finding223step 1 did not list is a rewrite that cannot fail or checks little (a weak oracle, a recomputed224expectation): the batch stops and names it until the rewrite is repaired. The re-scan sees only225the scanner's rules; the judgment-only shapes in `test-value` §5 stay with each rewrite's row226review.227228Then invoke `/mutation-testing:audit --exercised <folder> --replay-mutants <work>/before.tsv229--record-mutants <work>/after.tsv` through the Skill tool and read its `Gate:` line. The replay230reapplies each `before.tsv` mutant and compares the records mutant by mutant: one detected before231and not after is newly surviving.232233- A red replay baseline (a changed test fails on unmutated code) stops the batch and names the234 failing tests.235- `Gate: block`: the batch stops. For each `newly-surviving <path>:<line> <operator>` line, list the236 candidate changes: the batch's changed tests whose production files (step 5) include `<path>`,237 or every changed test when none does, since each mutant ran against the whole test set. The238 user reverts the ones they choose; then replay again. Cleanup reverts nothing itself.239- `Gate: pass`: go on.240- Any other outcome (no `Gate:` line, a refusal, a compare that could not run) stops the batch.241 Only `Gate: pass` reaches step 7.242243### 7. Report and commit244245Write the decision table and the gate result (K0 and K1, each newly surviving mutant with its246triage) to `<work>/pr-body.md`, and the findings file to the branch's findings directory,247`.work/reviews/<branch-slug>/<YYYYMMDDTHHMMSSZ>-testing-cleanup.md`, the slug and home as248`/review:fanout` "Shared inputs" defines them. One row per candidate that a rule selected, in the249shape `plugins/review/reference/findings-file-shape.md` gives: `Tier` and `Confidence` copied from250the source row, `Surface(s)` `testing:cleanup`, `Finding` the source row's `Finding` (rule id and251threshold first) followed by `cleanup row <n>: <action>`, `Action` reading252`applied by /testing:cleanup in this branch; review, do not re-apply` (or `kept: <reason>`). Quarantined tests have no rule and appear in253`pr-body.md` only, each with its expiry, owner and tracking issue, beside each expired quarantine254and the user's choice for it (re-enabled, escalated, renewed to a date, or undecided).255256Show the batch. While a yes-gated item is still unanswered, stop there and list it. Otherwise257commit the batch's files only (named paths, never `git add -A`) without waiting for a258batch-level approval: every yes-gated item in it already had the user's answer, and the commit259is local. Report the commit's SHA and how to undo it (while it is the branch's latest commit,260`git reset --soft HEAD~1` drops it and keeps its changes staged; later, `git revert <sha>`),261then delete `before.tsv` and `after.tsv`. Push and open the pull request only when the user262asks, through `/source-control:pull-request` when that plugin is enabled. Unattended runs stop263before the commit.264265## Cannot-fail-only mode266267For a folder no usable mutation tool can gate. Deleting a test that cannot fail loses no kill a268mutation run could record, so this mode deletes only such tests and needs no gate. It runs no test269and no mutation tool, so it is safe on suites whose tests reach live systems. It proposes no270quarantine, rewrite or merge. Step 0's branch, tree and folder checks still apply;271these steps replace steps 1 to 6, and step 7 follows unchanged.2722731. **Candidates.** Write `mode: cannot-fail-only` to `decisions.md`, and record each step reached274 as `cannot-fail-only <n>`. Run the step 1 scanner command and quarantine sweep, and record the275 scanner's `test blocks parsed` count in `decisions.md`. An in-scope row is one whose rule is276 `rule-zero-assertion`, `rule-recomputed-expectation` or `rule-inert-assertion` (section 5 of277 `${CLAUDE_PLUGIN_ROOT}/skills/test-value/SKILL.md` says what each means). The last two flag one278 statement, so a test is a candidate only when it has no assertion at all or every assertion in279 it is an in-scope row; a test with any other assertion is `not in this mode`. Every other row is280 out of scope, `rule-conditional-assertion` included (its assertion runs, and can fail, when the281 branch is taken), as are judge verdicts and tests the user names as flaky or duplicate: list each in `decisions.md` as `not in this mode` and leave it. So is a test in a282 `block_model: file` adapter's file, and a test holding a `catch ... when (...)` guard, such as a283 trial-license check: neither is deleted or edited. List expired quarantines found by the sweep,284 and change none. No candidate: report `nothing to clean in <folder>` and stop, unless step 2285 quarantined or re-enabled a test in this batch; then go to step 7 with those alone.2862. **Skeptic.** Per test file holding a candidate, write `<work>/skeptic-brief-<n>.md` from287 [`context/skeptic-brief.md`](context/skeptic-brief.md), with `<plugin-root>` rendered as288 `${CLAUDE_PLUGIN_ROOT}`, and dispatch a fresh-context `general-purpose` subagent with289 `model: opus`, for the reason step 4 (Classify) gives. Write its table to290 `<work>/skeptic-answer-<n>.md` and apply that file's reading rules: only a `cleared` row is a291 deletion candidate. Before the first skeptic, run292 `bash "${CLAUDE_PLUGIN_ROOT}/lib/read-verification.sh" --plugin testing --skill cleanup --file docs/conventions/testing.yaml` and copy293 its line into `decisions.md` ([levels](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/verification-level/README.md));294 `standard` and `strict` are this step as written. Under `light`, and `off`, which acts as `light`295 here, dispatch no skeptic and never clear a candidate in this context instead: each row's skeptic296 verdict reads `verification: skipped (<level>)`, no row is `cleared`, and this mode deletes nothing.2973. **Propose.** Fill `decisions.md` with one row per candidate: test, rule, quoted line, skeptic298 verdict, action, approved-by. A `cleared` row is a row 4 deletion whose no-contract statement is299 the skeptic's reason, unless a reference it quotes as naming a symbol elsewhere lies inside300 another `cleared` test: skeptics run per file, so two candidates can each be the other's only301 witness. That row is `keep: compile-time reference only in another candidate (<file:line>)`.302 Any other row is `keep`; when the skeptic names a statement that can throw, the action reads `keep: throw is the only oracle (<file:line>)`, which a gated run or a303 `cant-fail-ok: <why>` annotation can settle later.3044. **Delete.** Apply each deletion only after the user's yes to that item; unattended, apply none.305 Remove the whole test (its attributes, decorators and doc comment) and an import only it used,306 and nothing else: a helper or field the test alone used stays, for307 `/code-tidying:audit-dead-code`. Keep the file's line endings: a file whose every line ended in308 CRLF before the edit309 (`grep -c $'\r$' -- "<path>"` equals `wc -l < "<path>"`) still does after it. The310 `test-change: cleanup row 4: <reason>` comment rule of step 5 applies.3115. **Check.** Re-run the scanner over the folder. Its `test blocks parsed` count must be the count312 `decisions.md` recorded in step 1 minus the approved deletions, and `git status --porcelain`313 must list only files under the folder. Any other result stops the batch and names the difference.314315Step 7's report states that the batch ran in this mode, which step 0 check or step 3 result led to316it, if any, and that no mutation gate ran; it has no K1, and no K0 beyond that step 3 result.317Every deletion here is gate-blind by construction. It also states that nothing was built or318linted: a helper the deleted test alone used can trip an unused-code check, so ask the user to319build and lint the test project before pushing the batch.320321## What this skill does NOT do322323- Commit a batch before showing it, while a yes-gated item is unanswered, or in an unattended324 run; push it unasked; or delete, merge or revert any test without a yes on that item.325- Detect flaky tests, sweep quarantines outside the named folder, file a tracking issue, or bisect326 a lost kill.327- Clean more than one folder in one batch (a repository plan runs each folder as its own batch),328 or turn the `test-weaken` hook off.329330## Next331332- Open the batch's pull request with `pr-body.md` as its body: /source-control:pull-request create333- A deletion left an export, global or wrapper with no production caller: /code-tidying:audit-dead-code334335## Gotchas336337- **The gate is necessary, not sufficient.** A replay that passes says no recorded kill was lost.338 It says nothing about behavior no mutant reached, so every deletion still needs its row 4 or 5339 reason and the user's yes.340- **"No caller found" is not a no-contract statement.** A contract reached through dependency341 injection, reflection or an HTTP route does not show up in a search; that test is rewritten or342 kept.343- **The gate compares sets, not tests.** A weakened test passes the gate when another changed test344 in the batch now kills the same mutants. Each rewrite is still reviewed on its own row; per-test345 kill attribution is not built.346- **Cleanup never edits production code.** The replay refuses when production changes, so an export347 whose only caller was a deleted test stays until a separate dead-code pass removes it.348- **In cannot-fail-only mode the skeptic is the only check.** A test with no assertion still fails349 when its setup throws: a constructor, a dependency-injection resolution, a fixture. On one large350 .NET suite, skeptics rejected 3 of 42 proposed deletions for that reason.351- **A record outlives nothing.** Production code that changes between the two runs makes the replay352 refuse. Finish a batch before rebasing it.