PR audit

A skill that reads a pull request the way a careful senior reviewer would: first what it's for, then whether it works, then whether it will still be easy to change in six months. It ends with a verdict: Ship, Ship after fixes, or Hold.

Why I built it

An AI review that names every principle it can find is noise. You get thirty comments, three of them matter, and you stop reading. I wanted a review that only reports what it can back with a line number and a concrete failure, and that knows when a law doesn't apply.

Where it comes from

This skill isn't fully original. It's a combination of review skills I already use, put together into one pass that fits how I work:

pr-review-code-simplicity from Infinum's AI workflow: reviewing a PR through laws of software design, with an eye on long-term maintenance cost, and ending with a verdict.
requesting-code-review from Superpowers by Jesse Vincent: a review before you merge, with issues reported by severity.
Security review from Anthropic's Claude Code: a separate look at the diff for security problems, with false positives filtered out.

My part is the glue: the five passes in a fixed order, house rules beating the generic laws, and the gate that drops any finding without a file, a line and a failure scenario. The originals are worth a look on their own too.

How it works

It starts with scope: the diff, the PR description and the repo's own rules. House rules beat the generic laws, so if the repo says "no classes", it won't ask for an interface. Then it writes one sentence on what the PR changes. If it can't, that's the first finding.

Then five passes, always in the same order. Every finding has to get through one gate: a file and line, and a failure written as a scenario. A finding without a scenario is dropped.

Five review passes (correctness, laws of code, security, tests, accessibility) merge into one verify gate, then findings sort into Blocker, Should fix and Nit, each mapped to a verdict — Five passes, one gate, a verdict.

The laws of code

The second pass checks SOLID, DRY, KISS, YAGNI and the Law of Demeter, plus separation of concerns, least astonishment and fail fast. Each law in references/laws.md comes with two halves: what it looks like in a diff, and when to leave it alone. The second half matters most. Duplication twice is fine. An abstraction for one caller is not.

Table of nine laws of code, from single responsibility to the Law of Demeter, with when to flag each one and when to leave it alone — The laws, and when to leave them alone.

Security, tests and accessibility get their own passes. Security checks every new route for who can call it, untrusted input, secrets and new dependencies. Tests asks one question: if I revert the change, does a test go red? Accessibility only runs when the PR touches UI.

When to use it

Before you push, on your own branch.
As a first pass on someone else's PR, before you read it yourself.
Not as the sign-off. A person still approves the merge.

How to use it

Install it: unzip it into your skills folder (the command above).
Ask for an audit: "Audit PR #42", or "Audit this branch against main". For a branch it runs scripts/collect.sh to list the changed files, the size and the tests touched.
Read the verdict and the blockers first. Nits are capped at five.
Ask it to fix things only if you want that. It doesn't post to GitHub or change code on its own.

Example

A finding looks like this (made-up PR):

Code

2. Price rule copied into checkout · DRY · src/cart/checkout.ts:88
   The 20% VAT calculation from src/cart/total.ts:41 is pasted here.
   A rate change updates the cart total but not the checkout total,
   so the customer is charged a different amount than shown.
   Fix: import calcVat() from total.ts and delete the copy.

What's inside

SKILL.mdMarkdown

---
name: pr-audit
description: Review a pull request against the laws of code (SOLID, DRY, KISS, YAGNI, the Law of Demeter), plus security, tests and accessibility, and write a ranked report with a verdict. Use when asked to audit, review or check a PR, a branch or a diff before it merges.
---

# PR audit

Reads a pull request the way a careful senior reviewer would: first what it is for, then whether it works, then whether it will still be easy to change in six months. Every finding has to point at a line and say what goes wrong. A law that is broken but costs nothing is not a finding.

## 1. Scope

1. Find the diff. For a PR number, use `gh pr view <n>` and `gh pr diff <n>`. For a branch, run `scripts/collect.sh [base]` (defaults to `origin/main`). It prints the changed files, the size of the change and which tests were touched.
2. Read the PR description and the linked issue, if there is one.
3. Read the repo's own rules first: `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, the linter and formatter config. **House rules beat the generic laws.** If the repo says "no classes", don't ask for an interface.
4. Over about 800 changed lines? Say so in the report, and review the riskiest files first: anything that touches auth, money, data deletion or a public API.

## 2. Intent

Write one sentence: what this PR changes, for whom. If you can't, that is the first finding ("the PR does three unrelated things, split it").

## 3. Five passes

Do the passes in this order and keep notes per pass. `references/laws.md` has the full checklist, what each law looks like in a diff and when *not* to flag it.

1. **Correctness.** Does it do what the description says? Edge cases: empty, null, one, many, very large, concurrent, offline, a second click. Errors handled where they can happen, not swallowed.
2. **Laws of code.** SOLID, DRY, KISS, YAGNI, the Law of Demeter, plus separation of concerns, least astonishment and fail fast. Only within the code this PR touches.
3. **Security.** Untrusted input, injection, authorisation on every new route or action, secrets, new dependencies, personal data in logs.
4. **Tests.** Changed behaviour has a test, the test would fail without the change, nothing is skipped or loosened to go green.
5. **Accessibility.** Only when the PR touches UI: semantics, names and labels, keyboard and focus, contrast, motion, alt text.

## 4. Verify before you report

For every finding:

- Re-read the code around it. Check it isn't handled somewhere else (a middleware, a base class, a wrapper).
- Cite `path/to/file.ext:line`.
- Write the failure in one sentence: *with this input or in this state, this goes wrong*. For a design finding, name the change that will hurt: *adding a second payment provider means editing these four files*.
- Can't write that sentence? Drop the finding.

## 5. Report

Use `references/report.md`. In short:

- **Verdict:** Ship, Ship after fixes, or Hold. One line on why.
- **Findings,** most severe first, in three groups: Blocker (wrong result, data loss, security hole, broken build), Should fix (will cost real time later), Nit (taste, at most five). Each finding names the law or pass, the file and line, what goes wrong, and the smallest fix.
- **What's good:** up to three things worth keeping, so the author knows what not to undo.

## Rules

- Laws are trade-offs, not commandments. Duplication twice is fine. An abstraction for one caller is not.
- Review the PR, not the codebase. Old problems in untouched code go in one line at the end, if at all.
- Don't post comments to GitHub, push or change code unless you're asked to.
- Never paste secrets, tokens or customer data into the report, even when you find them. Say where they are and that they need rotating.

Changelog

v1.08 Nov 2026First version: five passes, a verify gate and a ranked report with a verdict.

Who made it

Vedran PetračAuthorI build apps and websites, and the odd maths model.About me

How it runs