Code quality, CLI, and test-writing guidelines with emoji enhancement
- version
- 1.42.0
- GitHub stars
- 20
Install
/plugin install code@motlin-claude-code-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add motlin/claude-code-plugins.
Contents
Discovered from sourceSkills 11
Build Warnings
A healthy build is quiet. Every warning the build prints trains readers to skim past the next one, and the one that matters, such as a deprecation that becomes a removal in the next upgrade, gets lost in the noise. Fix what the build warns about so that a new warning stands out.
Resolve <plugin-root> first: in Claude Code use ${CLAUDE_PLUGIN_ROOT}; in Codex use the plugin root that contains this skills/build-warnings/SKILL.md file. The script below needs Python 3.9 or later.
Arguments
- Command: the build and test command. Without one, find it the way burn does: git-test config (
git config --get-regexp '^test\.'),justfilerecipes,package.jsonscripts, a Makefile, then build files. - Scope: a directory or file set to limit fixes to. Defaults to the whole repo. The build always runs whole, since that is how its output is produced.
unattended: passed by callers such asburn. An unattended run asks the user nothing. Every question it would have asked becomes a queued finding instead (see Report).
Measure once, then fix classes
Run the build once and save the grouped report:
python3 <plugin-root>/scripts/build_warnings.py --root . run --log <scratch>/before.log -- '<command>' > <scratch>/before.json
One quoted argument runs in a shell; several run directly. The report groups warning lines by kind (compiler, lint, deprecation, runtime, slow-test, noise, other) and by what they share: a rule id, a deprecated API, or a file. Each group has a count, the files it names, and thirdParty, which is true when every file lies outside the repository's control (node_modules, site-packages, vendor and the like). --slow <seconds> sets when a test duration counts as slow, 1 second by default.
The baseline must pass: if the build or tests fail, stop and report it, because this skill never fixes a broken build. Read before.log around each group's example as well, since a warning the script files as other may still be fixable. Work through the groups with the highest counts first, fixing one class at a time: one rule, one deprecated API, one source of noise.
Fix the cause, never silence it
- Compiler and lint warnings: change the code the rule points at.
- Deprecations: move to the replacement the warning names. For a deprecated dependency, upgrade it to a version without the deprecation, within its current major version; a major upgrade is a finding, not a fix.
- Runtime warnings in tests: fix the code or test that triggers the warning, such as an unclosed resource or a missing await.
- Noise: remove leftover debug prints. For a log line that is legitimate but noisy in tests, capture it in the test that triggers it and assert on it, rather than lowering the level.
Never add suppression comments (# noqa, // eslint-disable, @SuppressWarnings, #[allow]), never lower a log level or a linter's severity, and never pass flags such as -nowarn, -w or --no-warnings to hide output. The only exception is a warning that comes from third-party code outside the repo's control and that no upgrade fixes: queue it instead of fixing it, with the dependency and its version.
Slow-test groups are not fixed here. Hand them to the code:test-speed skill, or queue them for it in an unattended run.
Verify with the same command
After each class, rerun exactly the same command and compare:
python3 <plugin-root>/scripts/build_warnings.py --root . run --log <scratch>/after.log -- '<command>' > <scratch>/after.json
python3 <plugin-root>/scripts/build_warnings.py compare <scratch>/before.json <scratch>/after.json
compare prints each class's count before and after and exits 1 unless the total fell. Keep a fix only when the build and tests still pass and the class's count fell without another class growing. Otherwise revert it and record the failing output. Do not try a different fix for the same class: move on.
Commit once per class, with a message that names the class and its counts, such as "Replace the deprecated fake_old() call (DeprecationWarning, 4 to 0)". Follow the repository's commit conventions.
Report
Report in the terminal, or return to the caller when unattended:
- each fixed class, with its count before and after from
compare; - each reverted fix, with the failing command and output;
- the classes left in place, and why.
An unattended run also returns its queued findings as task text the caller can append to .llm/todo.md: third-party warnings no upgrade fixes, major-version upgrades that a deprecation needs, and slow tests for code:test-speed. Each finding names the class, its count, the files, and the report's example line.
CLI Guidelines
cdis replaced withzoxide. Usebuiltin cdto change directories; thecommandprefix makes zsh run an external no-opcdthat leaves the shell where it was. No other command needs a prefix; don't writecommand git.- Avoid changing directories at all. Instead of
cd <dir> && git <subcommand>, rungit -C <dir> <subcommand>. - Prefer long flag names:
git commit --message, notgit commit -m.
Code Generation Formatting
Java code generators that build source via string concatenation need // @formatter:off / // @formatter:on guards. Without them, IntelliJ's formatter splits concatenation chains and breaks the correspondence between Java source lines and generated output lines.
The rule
Each \n-terminated line of generated output occupies exactly one Java source line. A Java line break occurs only where the template has a \n.
Bad (auto-formatted):
setterBody = ""
+ " domainObject.get"
+ propNameUpper
+ "().clear();\n"
+ " return;\n";
Good:
// @formatter:off
setterBody = ""
+ " domainObject.get" + propNameUpper + "().clear();\n"
+ " return;\n";
// @formatter:on
Finding violations
Look for concatenation blocks containing \n literals that are not inside // @formatter:off. Typical shapes:
- Multi-line
+chains with template variables split from their surrounding string literals. .collect()lambdas whose single-line template was broken across lines.return ( "" + ... )wrapped in parentheses instead ofreturn "" + ....
Fixing
Wrap the block in // @formatter:off and // @formatter:on, and collapse each \n-terminated segment onto one line with + continuation. A .collect() lambda with a single-line template goes entirely on one line. When the strings contain valid Java source, add // language=JAVA after // @formatter:off for IntelliJ language injection.
Match the indentation of existing @formatter:off blocks in the file. The usual pattern is tabs with aligned +:
// @formatter:off
// language=JAVA
return ""
+ "package " + packageName + ";\n"
+ "\n"
+ "public class " + className + "\n"
+ "{\n"
+ "}\n";
// @formatter:on
// @formatter:off
String fields = properties
.collect((p) -> " public final " + this.getType(p) + " " + p.getName() + ";\n")
.makeString("");
// @formatter:on
Code Quality Guidelines
Don't write forgiving code
- Accept one input format. In TypeScript, avoid union types (
|). - Validate inputs with preconditions or schema libraries. When expectations are violated, throw instead of logging.
- Don't add defensive try/catch blocks; let exceptions propagate.
- Delete legacy code paths instead of keeping them as compatibility fallbacks.
Naming
Don't abbreviate: number, not num; greaterThan, not gt.
Files
Confirm with the user before creating a new markdown file.
Emoji
Emoji and unicode characters are welcome at the start of comments and in doc headers.
Dead Code
Delete code nothing uses. Dead code costs reading time, review time and build time, and it misleads: a reader assumes it matters. A wrong deletion costs more than a missed one, so every removal carries evidence, and anything a tool cannot see into stays.
Resolve <plugin-root> first: in Claude Code use ${CLAUDE_PLUGIN_ROOT}; in Codex use the plugin root that contains this skills/dead-code/SKILL.md file. The script below needs Python 3.9 or later.
Arguments
- Scope: a file, a directory, or the whole repo (the default). Only code in scope is removed, but references are always searched across the whole repo.
unattended: passed by callers such asburn. An unattended run asks the user nothing. Every question it would have asked becomes a queued finding instead (see Report).
Detect from the entry points
Analyze reachability from the program's entry points, not one symbol at a time. Whole-graph analysis finds chains of code that only dead code calls; Meta's SCARF removed about 50% more once it switched to it (https://engineering.fb.com/2023/10/24/data-infrastructure/automating-dead-code-cleanup/). Find the detectors the project already has:
python3 <plugin-root>/scripts/dead_code.py --root . detect
detect recognizes these and prints their commands:
- knip, run twice: by default, then with
--production, which also reports code that only tests use; - vulture for Python;
deadcode -testfor Go, with-whyliveto show why a symbol it keeps is alive;- cargo-machete for unused Rust dependencies;
- OpenRewrite's private-only
RemoveUnused*recipes for Java, through the Maven rewrite plugin.
The baseline must pass: if the build or tests fail before any change, stop and report it, because this skill never fixes a broken build. Never install a detector or add it to the project's dependencies: an interactive run asks first, and an unattended run queues the suggestion and falls back to the method below.
Without a detector, list candidates from the language server's find-references, or by reading the scope for definitions, and check each one with a repo-wide grep that includes string matches:
python3 <plugin-root>/scripts/dead_code.py --root . refs <symbol> --definition <file>:<line>
refs greps tracked files for the symbol as a whole word, string matches included, leaves out the definition, and splits the rest into code and tests. Its verdict is unreferenced, test-only or referenced. A string match counts as a reference until you have read it and shown it names something else.
Fix the configuration before ignoring anything
A detector that reports live code as dead usually lacks an entry point or a framework plugin. Fix its configuration first: entry files, workspaces, framework plugins. Record a genuine exception in the tool's own allowlist (knip config, vulture whitelist, cargo-machete metadata), never in this skill and never as a suppression comment (https://knip.dev/guides/handling-issues). In an unattended run, configuration changes go in their own commit, so a reviewer can judge them apart from the deletions.
Sort candidates into tiers
- High: the detector reports it and
refssaysunreferenced. - Medium: the detector alone reports it, or
refssaystest-only. - Low: anything a static tool cannot see into: exported or public API, framework entry points, decorators and routes, dependency injection, reflection, code generation, plugin registries, and code with side effects at load time.
Remove only high candidates on your own. Code that only tests use counts as dead together with its tests, as in Google's Sensenmann (https://testing.googleblog.com/2023/04/sensenmann-code-deletion-at-scale.html), but deleting tests needs approval: an interactive run asks, and an unattended run queues the finding. Medium and low candidates are questions for the user in an interactive run and queued findings in an unattended one.
Remove in passes
Remove in this order: whole files, then exports and symbols, then dependencies. Removing a file can orphan the exports it used, and removing code can orphan a dependency, so rerun the detector after each pass and stop when it finds nothing new.
After each batch, run the build, the type checker and the tests. A batch that fails any of them is reverted and recorded with the failing output. Do not try a smaller batch or a different fix: move on.
Commit once per category: files, exports and symbols, dependencies, and configuration. Each message says why the code is dead, such as "no references outside its definition" or "knip reports the dependency unused". Follow the repository's commit conventions.
Never do any of these:
- remove code
refsreports asreferencedwithout reading every match; - delete a test that covers live code;
- add suppression comments or lower a detector's strictness to quiet it;
- change behavior while deleting, such as inlining or renaming what remains.
Report
Report in the terminal, or return to the caller when unattended:
- each removal, with its tier and evidence: the detector's line for it, or the
refsoutput; - each reverted batch, with the failing command and output;
- candidates left in place, with their tier and why.
An unattended run also returns its queued findings as task text the caller can append to .llm/todo.md: medium and low candidates, tests that only exercise dead code, and detectors worth adding. Each finding names the file, the symbol and the evidence.
Docs Drift
Docs drift when code changes and the prose does not follow. A wrong doc is worse than a missing one, because readers and agents act on it. Find the claims the code contradicts and fix them without rewriting anything else.
Resolve <plugin-root> first: in Claude Code use ${CLAUDE_PLUGIN_ROOT}; in Codex use the plugin root that contains this skills/docs-drift/SKILL.md file. The script below needs Python 3.9 or later.
Prior art worth reading for hard cases: drift-doc (https://github.com/raphabruno7/drift-doc) and doc-drift-detector (https://github.com/borghei/Claude-Skills/blob/main/engineering/doc-drift-detector/SKILL.md).
Arguments
- Scope: by default, the docs that name a file changed since the merge-base with the upstream branch.
allchecks every doc, optionally limited to directories; burn passesallwith a path shard. unattended: passed by callers such asburn. An unattended run asks the user nothing. Every proposed change becomes a queued finding instead (see Report).
List the docs
python3 <plugin-root>/scripts/docs_drift.py --root . docs --since "$(git merge-base HEAD @{upstream})"
python3 <plugin-root>/scripts/docs_drift.py --root . docs <directory>...
The doc set is README files, CLAUDE.md, AGENTS.md, SKILL.md and command files, outside vendored directories. Code comments are docs too, but the script does not list them: check comments in files within scope by hand, for the same kinds of claims. A doc nobody scans drifts unnoticed, so when the project keeps docs elsewhere, such as a docs/ site, add them to the list yourself.
Run the pre-pass
python3 <plugin-root>/scripts/docs_drift.py --root . claims <doc>...
The pre-pass is deterministic, so you judge only what it flags rather than reading every doc end to end. It checks:
- link targets and path-like code spans against the tree, resolved from the doc's directory and every directory above it, and against git renames, which catches moved and deleted files;
justrecipes and npm scripts named in code against thejustfileandpackage.json, in both directions: recipes the docs name that do not exist, and recipes no doc names;name@versionagainst the project manifest;- hard-coded counts such as "12 plugins".
It skips any line carrying a <!-- docs-drift: skip --> tag, so tag examples in prose that would otherwise be flagged.
Each claim has a status:
renamed, orcontradictedwith areplacement: a mechanical fix with a known one-to-one replacement.contradictedwith no replacement: the code disagrees, and fixing it needs judgment. Some of these are examples about another project, which are fine as written.check: a count to verify, or a recipe no doc mentions.
Check the rest
Beyond the flagged claims, read the behavior claims in scope: what a command does, its flags and defaults, what a function returns, what the configuration accepts. Compare each with the code, --help output or the parser. Verify links with lychee --offline --include-fragments <doc>... when lychee is installed.
Run a fenced command from a doc only when it is read-only, with a timeout and no network, and never one marked with a skip tag such as <!-- docs-drift: skip -->. Give every claim you checked a verdict of contradicted, unverifiable or OK, with the evidence: the file and line, or the command output.
Fix only what is mechanical
- Apply a fix on your own only when it is a one-to-one replacement: a renamed path, a renamed flag or recipe with a known successor, a stale version.
- Replace a hard-coded count with a pointer to where the number comes from, such as "the plugins listed in
marketplace.json", rather than updating the number. - Everything else is a proposed change: an interactive run shows it and asks, and an unattended run queues it.
Never do any of these:
- change source code to match a doc;
- rewrite prose the code does not contradict;
- restructure or reword a doc beyond the contradicted words.
Gate the result
Rerun the pre-pass with --strict on every doc you changed. It exits 1 while any mechanical fix remains:
python3 <plugin-root>/scripts/docs_drift.py --root . claims --strict <doc>...
Then commit the fixes, following the repository's commit conventions. When nothing was fixed, commit nothing.
Report
Report in the terminal, or return to the caller when unattended:
- each fix, with the claim, its replacement and the evidence;
- each contradicted claim left for a human, with the evidence;
- the docs checked, so a reader knows what was not.
An unattended run also returns its queued findings as task text the caller can append to .llm/todo.md: proposed rewrites of contradicted behavior claims, recipes no doc mentions, and counts that need a source. Each finding names the doc, the line, the claim and the evidence.
Markdown Authoring
Write each paragraph and list item on one line and let the renderer wrap it. Hard wraps make diffs noisy, since rewording one sentence reflows the whole paragraph, and they paste badly into GitHub text boxes. Code blocks, headings, and table rows keep their own line breaks.
Use - bullets instead of numbered lists, because numbers need renumbering on every insert or delete. When order matters, say so in the sentence before the list.
Test Coverage
Write tests that cover behavior nobody tested, in the code that changes most. Coverage is the measure, not the goal: a test that raises the number without checking behavior is worse than no test, because it hides the gap.
Load code:test-assertions, code:test-data and code:test-speed alongside this skill. New tests follow their shape: strict whole-value assertions, self-evidently fake literals, and extending an existing test file before creating one.
Resolve <plugin-root> first: in Claude Code use ${CLAUDE_PLUGIN_ROOT}; in Codex use the plugin root that contains this skills/test-coverage/SKILL.md file. The scripts below need Python 3.9 or later.
Arguments
- Scope: a file, a directory, or the whole repo (the default). Only files in scope are ranked.
unattended: passed by callers such asburn. An unattended run asks the user nothing. Every question it would have asked becomes a queued finding instead (see Report).
Measure the baseline
Detect the coverage tooling, then run it once and save the normalized report:
python3 <plugin-root>/scripts/coverage_baseline.py --root . detect
python3 <plugin-root>/scripts/coverage_baseline.py --root . run > "$WORKDIR/coverage-before.json"
detect recognizes Vitest, Jest, pytest-cov, Go, cargo tarpaulin, JaCoCo through Maven or Gradle, plus any just coverage recipe that writes coverage/lcov.info, and prints the command it would run. Pass --ecosystem <name> to run to pick one when several are detected. Put $WORKDIR outside the repository so reports are never committed.
When the project uses a tool detect does not know, or needs different flags, run the project's own coverage command and normalize what it writes with coverage_baseline.py parse --format lcov|cobertura|gocover|jacoco <report>.... When the project has no coverage provider at all, add one temporarily, and revert the dependency and lockfile changes before committing. An interactive run asks before adding one; an unattended run queues the question and stops.
The baseline must pass. If the suite fails before any change, stop and report it: this skill never fixes a broken build.
Pick targets
Rank files by churn times the uncovered share:
python3 <plugin-root>/scripts/churn_rank.py "$WORKDIR/coverage-before.json" --root . --paths <scope>...
The script skips generated, vendored, test, trivial and fully covered files, and files with no commits in the window (--since, default one year), and lists each skip with its reason. Work through the targets from the top.
Within a target file, the unit of work is the smallest public function or class that encloses uncovered or partially covered lines, about 50 lines at most. Split a larger unit by its public methods. Show the agent writing the tests that unit's source with its coverage tags, plus the existing test file for it so new tests match its style:
python3 <plugin-root>/scripts/coverage_baseline.py --root . annotate "$WORKDIR/coverage-before.json" <path>
! marks an uncovered line and ~ a line with an untaken branch. Without these hints, models write many more tests and most of them add no coverage.
Write the tests
Test the unit's public behavior: given these inputs, this output or this observable effect. Add new cases to an existing test file that already covers the area; create a test file only when none fits, at the lowest level of the pyramid that proves the behavior.
Never do any of these:
- write a test without assertions, a test that only calls getters, or a snapshot-only test;
- mock the unit under test;
- add coverage-ignore comments, or lower a coverage threshold;
- edit or delete an existing test;
- change production code, except a tiny refactor that makes a unit testable, which the report flags.
When covering a line would need one of these, skip the target and record why.
Accept or reject each test
Keep a new test only when all of these hold. Check them in this order, and drop the test at the first failure:
- It builds.
- It passes.
- It passes 5 repeated runs, plus a random-order or isolated run where the framework supports one. Repeating runs to find flakiness is measurement, not a retry.
- It lowers the target's uncovered or partially covered lines: rerun coverage for the test file and check with
coverage_baseline.py compare. - It is not a duplicate of an existing test: it checks something no existing test already checks.
Do not rewrite a rejected test and try again. Record the target as skipped with the reason (randomness, I/O, unreachable code, a failed acceptance check) and move on to the next target. Studies of generated tests found that only about a quarter raise coverage, so rejection is the normal case and these checks do real work.
Gate the result
When the targets are done, run the full suite and coverage again, then compare against the baseline:
python3 <plugin-root>/scripts/coverage_baseline.py --root . run > "$WORKDIR/coverage-after.json"
python3 <plugin-root>/scripts/coverage_baseline.py compare "$WORKDIR/coverage-before.json" "$WORKDIR/coverage-after.json"
compare exits 1 when no line or branch gained coverage, or when the total of covered lines dropped. Without a measured gain, the run failed: commit nothing and report why. With a gain, commit the new tests together, following the repository's commit conventions.
Report
Report in the terminal, or return to the caller when unattended:
- total coverage before and after, and per-file before and after for every changed file, from
compare; - each test added, with the target unit it covers;
- each target skipped, with its reason;
- any testability refactor made to production code.
An unattended run also returns its queued findings as task text the caller can append to .llm/todo.md: whether to add a coverage provider, untested code that looks dead, code that needs a design change before it can be tested, and any other judgment call. Each finding names the file, the symbol and the evidence.
Test Data Guidelines
Literal values in tests must be recognizable as fabricated. A reader should never wonder whether a value was copied from production.
Timestamps
Use memorable boundary dates, not specific-looking times:
# Bad: looks recorded from a real system
2023-11-14T22:13:20.000Z
# Good
1999-12-31T00:00:00.000Z
2000-01-01T00:00:00.000Z
Names and identifiers
Use the Alice/Bob/Charlie series or obviously generic names, with example.com (reserved by RFC 2606) for email:
# Bad: could be a real person, or the developer's own identity
user: "jsmith"
email: "john.smith@company.com"
# Good
user: "alice"
email: "alice@example.com"
Numeric IDs
Use round numbers or boundary values, not arbitrary numbers that look like real database IDs:
# Bad
id: 8847291
# Good
id: 100
id: 0
id: 2_147_483_647
id: 9_999_999
Paths and URLs
No real usernames, home directories, or system paths:
# Bad
path: "/Users/jsmith/.config/app/settings.json"
# Good
path: "/tmp/test/settings.json"
url: "https://example.com/api/v1/resource"
Test Mutation
Coverage shows which code ran; mutation testing shows whether any assertion would notice that code going wrong. Plant a small bug, run the tests, and if nothing fails, write the test that would have caught it. The mutation score is a signal, not a threshold: the output is tests that catch real bugs, not a number.
Load code:test-assertions, code:test-data and code:test-speed alongside this skill. New tests follow their shape: strict whole-value assertions, self-evidently fake literals, and extending an existing test file before creating one.
Resolve <plugin-root> first: in Claude Code use ${CLAUDE_PLUGIN_ROOT}; in Codex use the plugin root that contains this skills/test-mutation/SKILL.md file. The scripts below need Python 3.9 or later.
Arguments
- Scope: a file, a directory, or the whole repo (the default). Only files in scope get mutants.
unattended: passed by callers such asburn. An unattended run asks the user nothing. Every question it would have asked becomes a queued finding instead (see Report).- Time budget: 8 minutes of mutant runs by default. Stop planting new mutants when it runs out, and report what is left unvisited.
Pick lines to mutate
Mutants only belong on lines the tests already run. A mutant on an uncovered line survives by definition, and that gap belongs to code:test-coverage. Measure coverage first, with the same script that skill uses, then rank files by churn and pick lines:
python3 <plugin-root>/scripts/coverage_baseline.py --root . run > "$WORKDIR/coverage.json"
python3 <plugin-root>/scripts/mutation_targets.py --root . targets "$WORKDIR/coverage.json" --paths <scope>...
Put $WORKDIR outside the repository so reports are never committed. The baseline must pass: if the suite fails before any change, stop and report it, because this skill never fixes a broken build.
targets skips vendored, generated and test files, files with no covered lines and files with no recent commits, and lists each skip with its reason. In each remaining file it picks at most 7 covered lines, one mutant per line, preferring relational operators, then logical connectors, then return values, then arithmetic. It never picks arid lines: logging, time and deadlines, metrics, tracing and pre-allocation. A mutant there is either equivalent or a bug nobody would write a test for.
Plant the mutants
Use the ecosystem's mutation tool when the project has one, scoped to the picked lines or files:
python3 <plugin-root>/scripts/mutation_targets.py --root . detect
detect recognizes Stryker, PIT through Maven or Gradle, mutmut and cargo-mutants, and prints a command with {file}, {lines} or {class} placeholders. Never install a mutation tool or run its initializer: an interactive run asks first, and an unattended run writes mutants by hand.
Without a tool, write each mutant yourself on a picked line:
- flip a relational operator, such as
<to<=or==to!=; - swap a logical connector,
andforor, or drop a negation; - remove a statement;
- change a return value or a boundary constant;
- at most one realistic-bug mutant per function: the mistake a developer would plausibly make there, such as an off-by-one or a missed guard.
Apply one mutant, run the tests that cover the file, and restore the file byte for byte with git checkout -- <file> before applying the next. Never leave two mutants in place at once. A mutant the tests already catch is killed and needs nothing more.
Settle each survivor
Every surviving mutant ends in exactly one of these states:
- Killed by a new test that passes the acceptance checks below.
- Equivalent: no input can produce a different return value, state, output or message. State the argument in one line. Claim equivalence only after a genuine attempt to write a killing test, because models over-claim it.
- Queued for the user as a judgment call: behavior whose intended result is unclear, or a mutant that exposes a likely bug in the original. An interactive run asks; an unattended run queues it.
Spend effort first on survivors in rules that matter: money, permissions, eligibility, safety and data loss.
Write and accept the tests
Derive each expected value from intent: the function's name, its docs, the spec, or callers that rely on it. Never derive it by running the code and copying its output, because that locks in whatever the code does today, bugs included. When intent and the current behavior disagree, queue the finding instead of writing the test.
Keep a new test only when all of these hold. Check them in this order, and drop the test at the first failure:
- It passes on the original code.
- It fails with the mutant applied.
- It passes 5 repeated runs on the original. Repeating runs to find flakiness is measurement, not a retry.
- It kills at least one other mutant in the same function, or it fits naturally into an existing test. A test written to fit exactly one mutant is rejected.
Do not rewrite a rejected test and try again. Record the survivor as queued or skipped with the reason, and move on.
Never do any of these:
- edit or delete an existing test, except to add a case to a parameterized table;
- change production code;
- add suppression comments, skip or focus tests, or lower a mutation threshold.
Gate the result
When the budget is spent or every survivor is settled, prove that every hand-written mutant was restored and only tests changed:
python3 <plugin-root>/scripts/mutation_targets.py --root . changed
It lists changed files that are not tests and exits 1 when there are any. Restore those files before going on. Then run the full suite once. If it fails, or no test was kept, commit nothing and report why. Otherwise commit the new tests together, following the repository's commit conventions.
Report
Report in the terminal, or return to the caller when unattended:
- a table of every mutant: location, the change, its status (killed by an existing test, killed by a new test, equivalent, queued, not visited) and the killing test or the equivalence argument;
- the score before and after, as killed over killed plus survived, excluding equivalent mutants;
- each file skipped by
targets, with its reason.
An unattended run also returns its queued findings as task text the caller can append to .llm/todo.md: survivors that need a judgment call, mutants that expose a likely bug, whether to add a mutation tool, and code where intent is too unclear to test. Each finding names the file, the symbol, the mutant and the evidence.
Test Speed
Agents add a test or two with every change and rarely add assertions to an existing test, so after a long run of tasks a suite grows by hundreds of tests, each paying its own setup, and drifts toward slow end-to-end tests. Every extra second is paid on every commit gate and every CI run. Even 1% growth deserves attention because it compounds.
Load the code:test-assertions skill alongside this one. Folding tests together almost always means replacing scattered checks with one strict whole-value assertion, and that alone often nudges coverage up.
When writing a test during feature work
Extend an existing test before adding a new one. Look for a test that already builds the same setup (the same fixture, database, server, render, command invocation) or exercises the same subject, and add the new case there: a new field in its expected value, another row in its table of cases, another step in its scenario.
Red/green still applies. The red step is the extended test failing on its new expectation, then the implementation turns it green.
Add a new test only when no existing test fits, and write it at the lowest level of the pyramid that proves the behavior. Pure logic gets a unit test over the function, not a browser run or a full command invocation. If logic is tangled into a component or handler, extract the pure function and test that.
When running a speed pass
Run the pass directly when invoked. The user queues it as a task themselves when they want one.
Measure without running the suite twice
Running the suite once just to measure doubles the cost of the thing being fixed. Take timings from runs that happen anyway:
- Read the durations the normal gate already prints or saves: the test runner's summary line, per-file times from a verbose or JSON reporter, surefire XML reports, saved precommit or git-test logs.
- If the project records nothing usable, configure the runner to write per-file timings to a stable path on every run (a JSON reporter output file, surefire reports kept in place) and include that in the pass, so the next pass gets numbers for free. The
build:test-setupskill is the place to make git-test gates keep these logs.
Record the baseline: total duration, test file count, test count, and the slowest files.
Compare before and after with the same command under the same conditions. A recorded number is only a baseline if it came from that command; a suite timed inside a gate that also runs type-checking and builds runs much slower than the suite alone. When the recorded number is not comparable, one extra baseline run is worth it.
Run coverage twice for the whole pass, once on the starting commit and once at the end. Never rank or time files from a coverage run: instrumentation inflates some files by more than ten times and distorts the ranking. When the project has no coverage provider, add one temporarily and revert the dependency and lockfile changes before committing. Limit the coverage include pattern to source code files, since some coverage tools crash on stylesheets or JSON under the source tree.
Find where the time goes
The suite's wall time is usually bounded by total work across workers, not by its slowest file, so a small cost paid by every file can outweigh the slowest test.
- Check shared setup first: setup files, global setup, and test environment bootstrapping run once per file. Time a few tiny test files with and without the setup to see what each file pays before its first test. Runner import profiling (for example vitest
--experimental.importDurations.print) shows which imports dominate. - Then rank files by duration and by tests per expensive setup, and work from the slowest down. Reporter per-file durations often count only test bodies and leave out import, transform, environment, and setup time, so import-heavy files look cheaper than they are.
- Note where the runner splits time (tests, import, transform, environment, setup); a large import share points at setup files, file merging, and module loading rather than test bodies.
Apply the techniques
Fewer, fuller tests:
- Merge small tests that share setup into one test that builds the setup once and checks the whole result, so the database, server, render, or command runs once instead of once per case.
- Fold scenario tests into shared contract or parameterized tests when a test hierarchy or case table already exists.
- Merge tiny test files that import the same heavy modules, so imports and transforms happen once per worker. File-scoped module mocks and module-level singleton state (stores, registries, undo history) make a naive merge unsafe. Turning off per-file isolation as a quick probe shows which files share such state: files that break there need reset work before they can merge.
Load less in shared setup:
- When a setup file imports something heavy for every test file, make it lazy so only files that use it pay for it (for example wrapping a module through a module mock factory instead of importing it eagerly). Red-check the change: break the behavior the setup provides and confirm the same tests fail before and after.
Push down the pyramid:
- Rewrite end-to-end and browser tests that check pure logic as unit tests over that logic, extracting pure functions from components or handlers when needed.
- Keep end-to-end tests only for what lower-level tests cannot prove, such as wiring, routing, and real integration boundaries. Judge which survive case by case.
Build expensive fixtures once:
- Generate keys, parse large fixtures, and load heavy modules once per file or per worker rather than in every
beforeEachor test. - Build an expensive base state once (a fully migrated database, a seeded repository) and hand each test a cheap copy of it, keeping a test or two that exercise the real from-scratch path.
Remove real waits:
- Use fake timers instead of real ones, and wait for a condition instead of sleeping a fixed time.
- Scale timeouts, retry delays, and rate limits down in tests, keeping their ratios meaningful. When shortening a poll interval, raise the iteration count so the total wait budget stays the same; otherwise the test turns flaky under load.
- Use the smallest data that proves the behavior (100 rows, not 50,000). Check where a large size came from: it may track a batch or chunk size that has since changed. When the size must exceed a production constant, leave it unless a test seam for that constant is worth adding.
- Replace a test that waits for slow behavior to unfold with a direct check of the mechanism behind it, red-checked against the broken version.
Runner config levers:
- Share module graphs or workers between files where isolation is not needed (for example vitest
isolate: false), keeping files that need isolation in a separate isolated project. - Enable parallel execution where it is off (for example JUnit parallel execution, or more forks).
- Remove duplicate work in the gate, such as running the whole suite twice for a matrix or type-checking twice.
- Measure each lever on its own before keeping it; config changes can surface shared-state bugs.
Hold the line
- Never weaken an assertion. Every merged assertion's intent survives, written as a strict whole-value check.
- Never delete or skip a test unless its assertions live on elsewhere.
- Never raise a timeout to make a test pass. Speed comes from less work, not more patience.
- Never change production behavior. Extracting a pure function to enable push-down is fine.
- Line coverage must not drop by 1 percentage point or more, and should normally not drop at all. Explain any drop.
Finish
Make one commit if possible, splitting only when the diff is huge and each commit stays green. The commit message says the suite was sped up, with at most a ballpark such as "about 20% faster", since exact timings are machine-specific.
Report in the terminal: total duration, test file count, test count, and line coverage before and after; the slowest files before and after; and slow tests left unchanged, with the reason.
After a large run of tasks
When a branch or multi-task run added many tests or made the suite measurably slower, a speed pass is worth considering. Weigh it against how much the suite grew and suggest it, or queue it, when the growth is meaningful.
Commands 2
Add emoji to the content we're working on to make it easier to scan.
$ARGUMENTS
Put emoji at the start of headers, in lists and navigation elements, and in code comments.
Pick the best-fitting emoji for each element, then make a second pass replacing duplicates with suitable alternatives.
Keep usage consistent: match the content's tone (🎉 celebrations, 🔧 technical, 📚 documentation), use status indicators (✅ complete, ⏳ in progress, ❌ error, ⚠️ warning), and reuse one emoji per recurring label (📝 Notes, 🔗 Links).
Use the code:code-generation skill to find and fix every Java code generator string concatenation block containing \n that lacks // @formatter:off / // @formatter:on guards. Report what was fixed.
Sponsors
Details
- Marketplace
- motlin/claude-code-plugins
- Source
- plugins/code
- Author
- Craig Motlin
- Category
- Productivity
More from motlin/claude-code-plugins
All 30- code-walkthroughv1.42.0
- demov1.42.0
- ghostty-titlesv1.42.0
- gitv1.42.0
- git-guardsv1.42.0
- githubv1.42.0
- herdr-rebootv1.42.0
- herdr-titlesv1.42.0
- investigation-reportv1.42.0
- iterm2-titlesv1.14.0
- javav1.42.0
- justfilev1.42.0
- markdown-tasksv1.42.0
- narrationv1.42.0
- offline-claude-code-guidev1.14.0
- orchestrationv1.42.0
- plans-dashboardv1.42.0
- plugin-and-skill-devv1.42.0
- pushoverv1.14.0
- recapv1.42.0
- stop-phrase-guardv1.42.0
- temporal-datav1.42.0
- tmux-titlesv1.42.0
- upstream-syncv1.42.0
