About this template
The PR passed review and made billing import from the web layer
Tests green, style clean, two approvals. Nobody saw it, because a diff view shows lines — not directions.
Eighteen months later that import is why the billing rewrite takes a quarter.
It reviews the decision, not the code
Line-level review is a different job and other tools do it. This asks one question: does this change introduce, violate, or silently reverse an architectural decision?
Naming, style, micro-optimisation, test coverage — explicitly out of scope, and the review says so. Mixing both is what trains people to skim.
The rules come from your repo, never from taste
Before looking at a single hunk it reads your architecture documents —
docs/adr/, ARCHITECTURE.md, CLAUDE.md, AGENTS.md, CONTRIBUTING.md — and
extracts the rules with file:line provenance.
If your repo documents no architecture, it says so and stops. There's nothing to review against, and inventing rules is precisely the failure mode.
Every finding cites the recorded rule it violates. If no rule covers it, it's a QUESTION, not a violation — "this introduces a queue; there's no recorded decision about queues — is that intended?"
An architecture review that enforces the reviewer's unwritten preferences is how these get ignored.
Four things worth catching
- Layer / boundary violation — a module importing what the layering forbids. Highest-value catch, and usually invisible in a diff view.
- A new dependency direction — A now depends on B. Cheap to add, expensive to unwind.
- A silently reversed decision — the diff does the opposite of a recorded ADR without amending it. It names the ADR.
- A new integration point — a service, queue or datastore. Not wrong, but it should be a decision rather than an accident.
Severity is about reversibility
Ranked by how hard the change is to undo later, not how wrong it looks now. A sloppy function is cheap to fix; a dependency direction across a boundary isn't.
It cannot block you
No approvals, no blocking change requests, no required statuses. It comments when you ask, and never gates a merge — an agent that can block merges becomes something teams route around within a week.
What you supply
gh auth login with repo read + PR comment, plus your own Claude Code login. gh
ships at ~/.local/bin/gh.
Where this stops
It reads and drafts. It won't approve, block, merge, or set a status.
It won't call a design wrong on taste — cite a rule or ask a question. It won't claim performance impact it didn't measure, won't say a PR is safe to merge, and won't apply another project's conventions. Only your repo's documents count.
And when there's nothing to say, it says that in one line. A review that manufactures findings to look thorough is why people stop reading them.
Verified on build: the skill, the working tree, the NEVER_BLOCK_OR_APPROVE guard,
the cite-a-rule requirement, all four catches and a working gh are present on a
fresh fork. Running it on your own PR is yours to do.