From 60554cf407f53117d6a9e2f179fe8d634f9fdaf7 Mon Sep 17 00:00:00 2001 From: "blu@blu.cx" <38222767+thebrandonlucas@users.noreply.github.com> Date: Mon, 19 Oct 2026 19:07:09 -0500 Subject: [PATCH] docs(agents): require skill review and the CRAP report before review CI runs neither the voltage-pr-review skill's diff review nor the manual CRAP report, so both were easy to skip. AGENTS.md now lists the checks that authors and reviewers, people or agents, run before a pull request is ready: the skill review against the base, tests for every new error path, the development guide's gate, and the CRAP report for changes under src/ or tests/. The pull request reports what ran and the CRAP result. --- AGENTS.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ef560da..0a44a68 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,29 @@ Rules for coding agents working in this repository. Engineering conventions live change would exceed that, split the rest onto a new branch based on the one you changed and open it as a stacked pull request. +## Before you request review + +Authors and reviewers, people or agents, run the same checks. CI does not run all of them, +so a pull request is not ready until each one is done and reported. + +1. Review the diff against its base with the `voltage-pr-review` skill from + [voltagecloud/engineering-skills](https://github.com/voltagecloud/engineering-skills). + For Rust changes, also read the `voltage-backend-engineering` skill and its Rust style + checklist. Fix each applicable finding before you ask for review. +2. Test every new error and early-return path, not only the success path. +3. Run the verification gate in the [development guide](docs/development.md). +4. When the change touches `src/` or `tests/`, run the + [CRAP report](docs/quality.md#crap-risk-check). It is required even though CI does not + run it: every measured function must stay below 20. Fix a violation in the pull request + that introduces it, by adding meaningful tests or simplifying the code, never by + splitting functions only to lower the score. +5. In the pull request description, give the checks you ran and the CRAP result: the + highest score and each function at or above 20. Name any check you could not run, and + why. + +A reviewer runs the CRAP report on the pull request's head and reports each violation as a +finding, together with the review from step 1. + ## Agent friction log The CLI must be easy for AI agents to use. When it is not, record why in