agentleFS
million-viewsmillion-views/skills/test-audit/SKILL.md

test-audit

Skill2 starsChanged 49 days agoMITView on GitHub

Invoke whenever writing, changing, reviewing, or sweeping tests in this project. Provides an authoring gate that every new or changed test must pass, plus an audit workflow for finding and removing low-value, implementation-coupled, or duplicative tests and the test-only production seams they keep alive. Use it even when the user just says "add a test", "fix this flaky test", "clean up the test suite", "review these tests", or "reduce test bloat".

83 other projects use a version of this, 32 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use chips, redo and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • udecodeSkill

    chips

    Run the project's suggested-task ledger, the chips. /chips alone brings this session's open tasks up to date: it applies what the ledger helper says, settles stale and split tasks, cards what can start and reports the board, and /chips all also takes the ship-list tasks and the ones no live session owns, and merges duplicate tasks across the board. Use for /chips, /chips offer, start or drop, \"what chips are open\", \"suggest a task for X\", \"update the chips\", \"clean up the chips\", \"which chips are stale\", \"is this chip still worth doing\", \"merge duplicate chips\", at the last hand-back of a run that offered a task, and whenever pstack would file a tracked issue, a follow-up, a reflect Backlog item or an out-of-band PR.

    Also in 3 projects that use this

  • Scylla23Skill

    redo

    Re-run the last routed task one model tier up (haiku → sonnet → opus → fable). User-invoked escalation when the previous result missed. Pass --dry-run to preview without running.

    Also in 3 projects that use this

  • Aetheria-Labs1Skill

    plan-page

    Plan one storefront page from strategy through final copy, section order, proof, offers, template direction, responsive layout, and production asset requirements. Stops at an approved execution-ready specification.

    Also in 3 projects that use this

  • SocialKit-APISkill

    video-transcripts

    Extract transcripts from social videos through SocialKit across YouTube, TikTok, Instagram, Facebook, X/Twitter, LinkedIn, and direct video file URLs. Use when the user asks to transcribe, get captions or subtitles, pull the spoken text, or read what a video says, including one video or many at once. Returns full text plus timestamped segments. Not for posting, private accounts, or unrelated website scraping.

    Also in 3 projects that use this

  • clawdbotSkill

    pr-simplify

    Simplify your own change to its smallest complete fix. Use before opening a PR, before pushing large repairs to one, or when asked to shrink a PR or clean up slop.

    Also in 3 projects that use this

  • spitoglouSkill

    technical-documentation

    Create and improve technical documentation including architecture designs, PRDs, API docs, code explanations, and visual diagrams. Use when asked to document systems, explain codebases, create design documents, write PRDs, generate Mermaid/PlantUML diagrams, review architecture, write user stories, or create pull request descriptions. Triggers include "document this", "create a design doc", "explain this code", "write a PRD", "create a diagram", "architecture overview", "user story for", "PR description".

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. 0 are common, 12 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 80 edited versions we read keep these.

  • 12

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read the project's contributor and agent guidance (for example README, CONTRIBUTING, AGENTS.md, CLAUDE.md, or equivalent), including any …

    line 27
  2. Distinctive:

    Before adding any test, answer four questions.

    line 37
  3. Distinctive:

    Before judging a candidate, read the complete test and its production owner, the owner's entry point, callers, callees, sibling …

    line 98
  4. Distinctive:

    Keep discovery read-only and report evidence before editing.

    line 106
  5. Distinctive:

    Keep a test when it independently enforces a public API, protocol, wire or file format, configuration, migration, storage, security, …

    line 120
  6. Distinctive:

    call ordering when order is observable behavior.

    line 125
  7. Distinctive:

    Prefer net-negative production lines of code.

    line 156
  8. Distinctive:

    Never edit source or tests while a test runner or watcher is running against the working tree.

    line 162
  9. Distinctive:

    Run the smallest owner and sibling tests using the project's test runner with a path or name filter.

    line 165
  10. Distinctive:

    Run the project's formatter/linter on changed files, then git diff --check (or the equivalent whitespace check for your VCS).

    line 169
  11. Distinctive:

    Run whatever changed-files or pre-merge gate the project's policy requires (CI-equivalent lint, type check, and affected test suites).

    line 171
  12. Distinctive:

    After final audit edits, request or perform an independent review of the diff before landing.

    line 175
  13. Distinctive:

    Commit, push, open a pull request, or merge only when authorized, following the project's contribution workflow.

    line 180

“Common” is measured: kept by at least 6 in 10 of the 80 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Test Audit

Three modes, one value bar.

  • Authoring mode gates every new or changed test at write time.
  • Audit mode runs focused sweeps for tests that re-assert source, duplicate stronger proof, couple behavior to implementation, or keep test-only production seams alive. Continue broad audits as separate, coherent follow-up changes; optimize for confidence, not deletion count.
  • Campaign mode prunes one whole subsystem's test surface (every test file a module, package, or feature area owns). Before starting one, read CAMPAIGN.md.

Before you start

Discover how this project works rather than assuming:

  • Read the project's contributor and agent guidance (for example README, CONTRIBUTING, AGENTS.md, CLAUDE.md, or equivalent), including any scoped copies in subdirectories.
  • Identify the test runner, how to run a single file or filter, the formatter/linter, and the CI configuration that decides which tests run.
  • Identify the project's module or package boundaries: these are the "owner boundaries" referred to throughout this skill.

Authoring gate

Before adding any test, answer four questions. A missing answer means do not add it yet:

  1. What observable behavior, invariant, or independent contract does it protect?
  2. What credible regression makes it fail?
  3. Why does existing coverage not already catch that failure? Each contract has one primary test owner at the strongest boundary; another layer needs its own distinct risk, such as a transport or lifecycle failure the owner cannot reach. Prefer extending a table-driven/parameterized case or shared fixture over a near-duplicate test; consolidate duplicated setup in the same change.
  4. Does it need a production seam (export, flag, wrapper, injection hook) that no production caller needs? If yes, move the test to the real boundary instead.

Then check the test against every junk pattern; a match fails the gate unless the retention bar names the contract it independently guards. A test that would break under behavior-preserving refactoring is asserting implementation, not behavior; rewrite it at the owning boundary before landing it.

Bug regression tests must fail on the pre-fix code for the intended reason and pass after the owner-boundary repair. A regression test that never demonstrably failed proves the mock, not the fix. One regression at the owner boundary covers the bug; do not replay the same scenario at every layer it crosses.

Junk patterns

The shared checklist for all modes: the authoring gate rejects a new test that matches one, and audits hunt for existing tests that do.

  • assertion-free coverage probes;
  • self-comparisons and identity copiers;
  • copied fixtures, inventories, manifests, or export lists;
  • exact source, import, or string greps;
  • private predicate or call-shape tests duplicated at real boundaries;
  • duplicate invocations of the same contract;
  • per-module replays of shared helpers already tested at their owner;
  • tests whose only purpose is preserving test-only exports, globals, or wrappers;
  • dead production code whose only callers are tests;
  • expected values produced by the helper or renderer under test;
  • mocks that implement the asserted behavior, or one identical mock standing in for different APIs;
  • fixtures that supply the result, ordering, or callback sequence the code under test should produce, or persistence asserted against a store the code path never writes;
  • capability tests that restate declared flags or configuration instead of exercising the behavior the flag promises;
  • negative controls that pass for an unrelated reason, such as a denial from a different guard or a rejection the production path never reaches;
  • names or fixtures that promise more than the input exercises, such as a "clears the cache" test that asserts the cache was not cleared.

Value bar

Tests justify their maintenance cost by protecting behavior, a credible regression, or an independently meaningful contract. In an audit, an existing test that must change for behavior-preserving source reorganization is suspect, not automatically deletable; the authoring gate still rejects new ones.

Before judging a candidate, read the complete test and its production owner, the owner's entry point, callers, callees, sibling implementations, overlapping tests, CI routing, and relevant version-control history. When the test claims dependency-backed behavior, inspect the dependency's source or type definitions directly.

Discovery

Keep discovery read-only and report evidence before editing. For broad scope, run parallel discovery lanes when available, split along the project's own boundaries, for example:

  • core library or domain code;
  • plugins, extensions, or integrations;
  • UI, apps, CLIs, scripts, and tooling;
  • a cross-cutting pattern sweep for the junk patterns.

Outside campaign mode, prefer a few high-confidence candidates over a large speculative inventory.

Retention bar

Keep a test when it independently enforces a public API, protocol, wire or file format, configuration, migration, storage, security, platform, default value, generated or cross-language, packaging, release, or architecture contract. Also keep:

  • call ordering when order is observable behavior;
  • regressions with a credible failure mode;
  • source inspection when it is the cheapest independent guard: it fails when the contract changes (the user-facing key, byte, or path) and survives an identifier-only refactor;
  • a retained test that fails on the baseline: treat it as a possible product bug, reproduce it, and repair the owner rather than deleting it.

Static or slow is not a deletion reason. A test that resembles implementation may still be the independent contract; prove otherwise before removing it.

Candidate evidence

Record every field below before editing. A missing field means the candidate is not ready for deletion:

  • exact test name and location;
  • what failure it can actually detect;
  • non-test callers of the covered production or support seam;
  • stronger remaining owner-boundary proof, or why no proof is needed;
  • relevant history and the reason the test or seam exists;
  • production or test-support deletion unlocked;
  • risk and the focused validation command.

Edit shape

Choose one coherent owner-boundary batch. Delete obsolete test-only exports, globals, wrappers, and dead production paths instead of preserving aliases. Move retained regressions to their canonical owners. Consolidate repeated package or dependency assertions into one generic contract.

Prefer net-negative production lines of code. Do not add replacement tests that restate the same implementation, and do not convert uncertain candidates into cleanup to increase deletion counts.

Validation

Never edit source or tests while a test runner or watcher is running against the working tree.

  1. Run the smallest owner and sibling tests using the project's test runner with a path or name filter.
  2. For removed source greps or plan assertions, run the executable, script, or dry-run that owns the real contract.
  3. Run the project's formatter/linter on changed files, then git diff --check (or the equivalent whitespace check for your VCS).
  4. Run whatever changed-files or pre-merge gate the project's policy requires (CI-equivalent lint, type check, and affected test suites).
  5. Inspect git diff --numstat; report production/tooling changes separately from tests and test support.
  6. After final audit edits, request or perform an independent review of the diff before landing.

Landing and continuation

Commit, push, open a pull request, or merge only when authorized, following the project's contribution workflow. Land one coherent change at a time; after landing, refresh from the current main branch and rerun read-only discovery for the next high-confidence batch.

Handoff

Report:

  • root cause and removed low-value categories;
  • production owner simplifications;
  • retained false positives and why they remain valuable;
  • focused and full proof actually run;
  • production versus test lines of code;
  • pull request and merge state;
  • named follow-ups.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.