agentleFS
paureispaureis/pau-skills/skills/verification/review-triage/SKILL.md

review-triage

Skill2 starsChanged 24 days agoMITView on GitHub

Decide which review findings are worth fixing, fix those with a test each, and end the review and fix loop after one round. Use when the user pastes review findings or says 'triage these review comments', 'is this worth fixing', 'the review keeps finding things', 'what blocks the merge'. Sorts a review that exists.

8 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

7 rules. 0 are common, 7 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 7

    Distinctive

    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
  1. Distinctive:

    Do not fix a finding that names no failure.

    line 87
  2. Distinctive:

    Do not start a second fix round.

    line 88
  3. Distinctive:

    Do not fix something outside the change in this change.

    line 89
  4. Distinctive:

    Do not let a risky fix in for a minor problem because it is small.

    line 90
  5. Distinctive:

    Do not drop a security finding you could not settle.

    line 91
  6. Distinctive:

    Do not let a learned pattern or nitpick gravity skip checking a finding, a must-fix, or a security finding.

    line 92
  7. Distinctive:

    Do not re-review the whole change after the fix round.

    line 93

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

Review triage

Decide which findings from a review to act on, fix those with a test each, and stop after one fix round.

The findings: $ARGUMENTS

The method is in ${CLAUDE_SKILL_DIR}/TRIAGE.md. Read it before triaging anything; the steps below refer to its sections. ${CLAUDE_SKILL_DIR}/review-scope.mjs (Node 20+, no dependencies, read only) prints the project's rules, the files a change touches, and the flags for a fix round.

Steps

  1. Load the project's rules. node "${CLAUDE_SKILL_DIR}/review-scope.mjs" config It prints the must-fix list (the defaults plus the project's own), the risky paths and the checks. Without .claude/review-rules.json the defaults apply. If the project has an obvious core where a small mistake is expensive (money, credentials, deletion, the code that decides what runs where) and no file names it, offer to write one: show it, and write it only on a yes. If the project keeps learned review patterns (section 9 of TRIAGE.md, for example in .claude/review-patterns.md), read them too.
  2. Scope the change. node "${CLAUDE_SKILL_DIR}/review-scope.mjs" change --base <base branch> It lists every file the change touches, which of them are risky, and whether any test changed. When the work is committed on the base branch itself, pass the commit it started from as --base.
  3. Collect the findings. From the arguments, the pull request's review comments, or a review file. If there are none and the user wants a review, run one first, and give the reviewer the prompt at the end of TRIAGE.md.
  4. Triage every finding with sections 1 to 4 of TRIAGE.md: name the failure, check the claim, rate it, pick the bucket. Then write the table from section 5, and decide whether nitpick gravity (section 4) applies to the whole review. Show the table to the user before fixing anything when a finding is a must-fix you could not reproduce, a security finding you could not settle, or a call that is the maintainer's. When a kind of finding keeps coming back, propose a learned pattern (section 9): you may add a candidate, but ask before creating the patterns file; a move to recurring or strong waits for a yes.
  5. Fix round, section 6: commit the reviewed state, write a failing test for each fix first, fix, then run node "${CLAUDE_SKILL_DIR}/review-scope.mjs" fix --since <reviewed commit> (add --base <start commit> when the work is on the base branch itself) and answer every flag.
  6. Second look on the fix only, with the git diff command the script prints and any new files it lists. Then stop, by section 7.

Configuration

Optional .claude/review-rules.json in the repository. Every key is optional:

{
  "mustFix": ["a command runs against the wrong account", "a test touches a real external service"],
  "riskyPaths": ["src/core/decide/**", "migrations/"],
  "checks": ["make test", "make lint"],
  "testPaths": ["checks/**"],
  "docPaths": ["handbook/**"]
}

mustFix is added to the defaults. testPaths and docPaths replace the defaults, which cover the common layouts of most ecosystems (run config to see them). Paths are globs relative to the repository root. An unknown key is an error, so a typo cannot switch a rule off without anyone noticing.

Report

Review triage: <change or pull request>
Findings: <n> (must fix <a>, fix if cheap <b>, leave <c>)
<the table from TRIAGE.md section 5>
Nitpick gravity: <applied: every finding was a preference or a low-value nit, the change is probably fine | not applied>
Learned patterns: <used: names | added as candidate: names | waiting on a yes: names | none>
Fix round: <commits>; fix check flags: <none | each flag and how it was answered>
Second look: <clean | what it found, and where it went: maintainer or issue>
Issues to open: <list, or none>
Waiting on the maintainer: <list, or none>

Do not

  • Do not fix a finding that names no failure.
  • Do not start a second fix round. What the second look finds goes to the maintainer or to an issue.
  • Do not fix something outside the change in this change. Open an issue.
  • Do not let a risky fix in for a minor problem because it is small.
  • Do not drop a security finding you could not settle. Ask.
  • Do not let a learned pattern or nitpick gravity skip checking a finding, a must-fix, or a security finding.
  • Do not re-review the whole change after the fix round. Look at the fix.

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.