correctness
Skill0 starsChanged 56 days agoMITView on GitHub
Review a working change for defects (logic, state, lifecycle, concurrency, regression) and for drift from its ticket, docs, and rules, then apply what you accept.
In this repository26 other files it gives its agents.
- ask-mattSkill
- create-prSkill
- draft-prSkill
- ready-prSkill
- developSkill
- self-review-docsSkill
- implement-reviewSkill
- implementSkill
- implement-specSkill
- librarianSkill
- nemesisSkill
- refactorSkill
- research-codebaseSkill
- researchSkill
- review-docsSkill
- self-reviewSkill
- shapeSkill
- tddSkill
- test-auditSkill
- waterfall-challengeSkill
- waterfall-designSkill
- waterfall-implementSkill
- waterfall-planSkill
- waterfall-refactorSkill
- waterfall-reviewSkill
- zero-tech-debtSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
If the reviewers report no findings, go to step 7.
- Distinctive: line 67
Treat input from across a trust boundary as tainted, and trace it to every sink it reaches.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Correctness
Run
- Diff the review target: the current branch against its merge-base with the default branch, plus uncommitted changes, unless the invocation names another target.
- Spawn five reviewers in parallel: one for Logic and Concurrency, one for State, one for Lifecycle, one for Regression, and one for the Contract axes, leaving out Spec when the change has no ticket.
- If the reviewers report no findings, go to step 7. Otherwise, spawn one verifier with the Evidence and Verify sections copied verbatim, the review target, and every finding as its line, trigger, and failure, without the reviewer's reasoning.
- Merge the confirmed and dependent findings that one fix resolves, keeping each one's trigger.
- Apply each confirmed Contradictions finding whose fix changes only a comment, docstring, doc, or example to match what the code does.
- Present each other merged finding with its triggers and failure, the fix you would apply, any fact it depends on, and your recommendation with its reason, and wait for the person to accept or decline it. List the refuted ones in a line each with the code the verifier cites, so the person can overrule it. Apply the accepted ones.
- End with the findings by axis, sorted by file and line, which you applied, and the decisions they leave the person, each with your recommendation.
Give every reviewer the Scope, Evidence, and Report sections and its own axis sections, copied verbatim, plus the review target and the ticket. Give each Behavior reviewer the paragraph under Behavior as well, and the Contract reviewer the path of the user-level instruction file your harness loads. Add nothing of your own reading.
Scope
Review the axes your task names. Other reviewers cover the other axes; leave their findings to them.
Evidence
A finding names the input or state, the changed line, and the failure that follows: a wrong result, a crash, lost data, or a broken contract. Report a defect only when the change causes or worsens it, or when the code misses an outcome its ticket asks for or breaks a written rule that governs it, and cite the line that does. Trace the trigger through callers, guards, types, and configuration before you report it; a guard that rules it out refutes it. A defect that another defect hides today still counts; it depends on that fix.
Behavior
Trace the change end to end on every Behavior axis: follow each changed path from where its input enters to where its effects land, in storage, events, responses, or another process, across files.
Logic
What input makes a changed line compute the wrong answer? Apply boundary value analysis to each condition, index, and range the change touches. Treat input from across a trust boundary as tainted, and trace it to every sink it reaches. Check that queries, units, and clocks mean what the code takes them to mean. Find silent failures: an error swallowed, or a fallback that reports success under a broken assumption.
State
What invariant can the change leave broken? Name the invariants the changed code relies on or maintains, then find every write that can break one, outside the diff as well. An invariant can hold before and after a multi-step update but not between its steps; find who reads it there. Where data has a single source of truth, find the copies, caches, and derived values the change lets drift from it.
Lifecycle
What does the change start, hold, schedule, or store, and when does each end? Check exception safety: on every exit, early returns and failures halfway included, it is released or completed. Find what never ends or expires and builds up. Ask what happens when its owner ends first, when the process restarts and memory is lost, and when it runs twice: an operation that can be retried must be idempotent. An effect that escapes before its transaction commits outlives a rollback. What the change stores may meet data written before it, or code from another version; report that only when the repository shows them meeting: existing records, a rolling deploy, or a published format.
Concurrency
What runs at once on shared state? Establish the happens-before order the changed code relies on, and find where nothing enforces it. A check-then-act breaks when the state can change between the check and the act. Report a race only when tasks that really run at once share the state.
Regression
What did the old code guarantee that the new code no longer does? Read the old code beside the new: for each line the change deletes or replaces, and each path it moves or rewrites, name what it enforced (a guard, an order, a window, a side effect, a retry) and find where the new code enforces it again. Respect Chesterton's fence: a guarantee nobody wrote down still counts.
Contract
Spec
Does the change deliver the outcomes its ticket asks for? An outcome is behavior a user, caller, or peer observes. The rest of a ticket is a first sketch, written before anyone dug in, and context for the implementer. Find outcomes missing, partly met, or met wrongly, and observable behavior the ticket did not ask for. Quote the outcome. A ticket title is context, not a specification; without a usable spec, say so and leave this axis.
Contradictions
Does the change leave the code and its own claims disagreeing? Check the comments, docstrings, and docs the change touches or makes stale against what the code now does. Quote both claims with their locations and say which is wrong.
Conventions
Does a changed line break a rule from the instruction files that govern
it? Find them: the user-level file your task names, and each AGENTS.md
or CLAUDE.md at the repository root or in an ancestor directory of a
changed file, and the repository's CODING_STANDARDS.md, REVIEW.md,
and CONTRIBUTING.md when present, with the files they import or point
to. A directory's file binds only the files at or below it. Quote the
rule with its file and the line that breaks it; the spirit of a rule is
not evidence.
The design decisions bind it too: the ADRs in docs/adr/ and the root
GLOSSARY.md, and when a GLOSSARY-MAP.md lists contexts, the ADRs and
glossary of each context the change touches. An ADR binds while its
status is current and nothing supersedes it; quote its decision as you
would a rule. A glossary defines the domain terms the code and ticket
use. A missing document is not a finding.
Report
Return each finding with its file and line, its axis, the input or state that triggers it, the failure that follows, and any fact it depends on that the code does not show.
Verify
Findings may repeat across reviewers; trace a shared mechanism once and give each finding its own verdict. For each finding, read the cited line and trace its trigger to its failure through callers, guards, types, and configuration. Give one verdict:
- confirmed: the trace holds, and the change causes or worsens it.
- depends: it holds only if a fact the code does not show is true; name the fact.
- refuted: cite the code, at file and line, that rules it out, or the old code that had the same defect, or say that it names no failure.
Refute only by citing code. A finding you doubt but cannot rule out depends on the fact you would need.
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
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.

