agentleFS
Lukk17Lukk17/agent-standards/.agents/skills/quality-loop/SKILL.md

quality-loop

Skill1 starsChanged 3 days agoMITView on GitHub

The measure-and-fix loop for agent-written code, after Robert C. Martin: CRAP scores from crapper, duplicate pairs from dryer and surviving mutants from mutator, fixed worst first until clean or three rounds. Use when the user says "clean up this code", "run the quality loop", "measure the CRAP scores" or "find surviving mutants". Not for writing the tests of a new feature, use `tdd-workflow`.

9 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 1 is distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

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

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

    Run the tools only through the wrapper, .metrics/tools/run on Linux and macOS and .metrics\tools\run.cmd on Windows.

    line 41
  2. Very specific:

    Start with measure, a full run of all three tools, and read the result with summary.

    line 42
  3. Very specific:

    When .metrics/tools/run is missing, get the tools before anything else, the way the running reference says.

    line 43
  4. Very specific:

    After each round of fixes, run mutate --changed for the mutants and measure for the full scores, and keep the project's own tests green.

    line 48
  5. Distinctive:

    Stop when nothing is over the limits, or after three rounds, and report what is left with the reason it is left.

    line 49
  6. Very specific:

    Commit the fixes and the full-run scores in .metrics/ only when the caller asked for commits, with a JaCoCo block the wrapper added to a …

    line 50

“Common” is measured: kept by at least 6 in 10 of the 7 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

Quality Loop

Measure the code, fix the worst mess first, and measure again. The method and the three measuring tools are the work of Robert C. Martin (Uncle Bob): crapper scores every function by complexity and coverage, dryer lists functions with the same shape, and mutator plants small bugs and reports the ones the tests miss. A project carries his tools unchanged under .metrics/tools/, with a wrapper that runs them, and keeps the scores in .metrics/.

TaskOpen
Running measure, mutate --changed and summary, the exit codes, the first run, getting the tools into a project, Windows, what to commitreferences/running-the-tools.md
Reading .metrics/crap.edn, .metrics/dry.edn and .metrics/mutate/, and the bands that decide what must be fixedreferences/reading-the-scores.md
Fixing each kind of mess, per-language notes, and the before and after reportreferences/fixing-the-worst.md

When to activate

  • A feature is done and its code needs measuring before review, or the user says "run the quality loop"
  • The user says "clean up this code", "measure the CRAP scores", "find surviving mutants" or "find duplicated code"
  • A review cites a high CRAP score, a surviving mutant or a duplicate pair from .metrics/
  • The project is in Clojure, Java with Maven or Gradle, Go, TypeScript or JavaScript, Rust, or Python

When not to activate

  • Writing the tests of a new feature first, use tdd-workflow
  • Deciding whether two similar blocks are one rule, use review-duplication
  • Reviewing a change without changing it, use code-reviewer, which reads .metrics/ but never runs the tools
  • Kotlin, C#, PHP, Dart or any other language the tools do not read: report it as not measured
  • Profiling a slow path, use performance-optimization

Rules

  1. Run the tools only through the wrapper, .metrics/tools/run on Linux and macOS and .metrics\tools\run.cmd on Windows. Never edit anything under .metrics/tools/crapper, dryer or mutator, which is Robert C. Martin's code copied unchanged.
  2. Start with measure, a full run of all three tools, and read the result with summary. Never run crapper on changed files only: a partial run replaces .metrics/crap.edn with a subset.
  3. When .metrics/tools/run is missing, get the tools before anything else, the way the running reference says. Never write a tool of your own in their place.
  4. Fix the worst first: a CRAP score over 30, then every surviving mutant in code the change touched, then the duplicate pairs at or above 0.82.
  5. Fix a high CRAP score by splitting or simplifying the function, or by adding the test that covers it, whichever the function needs. Never raise coverage with a test that asserts nothing.
  6. Kill a surviving mutant with a test that fails on the mutated code and passes on the real code. Never weaken, skip or delete a test to make a score look better.
  7. Merge a duplicate pair only when both copies encode the same rule and change for the same reason. review-duplication and coding-standards decide, and a pair that only looks alike stays as it is.
  8. After each round of fixes, run mutate --changed for the mutants and measure for the full scores, and keep the project's own tests green.
  9. Stop when nothing is over the limits, or after three rounds, and report what is left with the reason it is left.
  10. Commit the fixes and the full-run scores in .metrics/ only when the caller asked for commits, with a JaCoCo block the wrapper added to a Gradle build file in its own commit. Otherwise leave them staged for the caller.

Limits

ScoreLimit
CRAPOver 30 must be fixed. A function the change touched aims under 10
Surviving mutantsNone in code the change touched
Duplicate pairsEvery pair at or above 0.82 is reviewed, not merged blindly

Related skills

  • tdd-workflow owns the red-green loop each new test follows
  • coding-standards owns how a function is split and named
  • review-duplication owns the call on whether a duplicate pair is one rule
  • code-reviewer reads .metrics/ and turns the worst scores into review findings

Checklist

  • The wrapper ran measure and summary, and no tool ran on its own
  • Nothing under .metrics/tools/crapper, dryer or mutator changed
  • Every CRAP score over 30 was fixed or reported with its reason
  • No surviving mutant is left in code the change touched, or each one left is reported
  • Every duplicate pair at or above 0.82 was reviewed, and merged only when both copies are one rule
  • No test was weakened, skipped or deleted
  • The project's own tests pass after the last round
  • The full-run scores in .metrics/ are committed when the caller asked, staged otherwise, and the report shows them before and after

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.