A Field Guide to Code SpecimensVol. I · No. 1 · MMXXVI

Clud Bug.

AI PR review with project-aware skills. Install the GitHub App, write a skill, get reviews graded against your conventions on every pull request.— Cluddus bugfindii, observed crawling on every PR.

§ I — Field Procedure

Three steps. Two minutes per review.

  1. 1

    Install

    Install the GitHub App on the org or repos you want reviewed. Approve the permissions for pull requests, contents, and checks.

  2. 2

    Authorize

    Pick a plan on the dashboard — managed tiers for any repo, public or private. The bot reviews against the skills in .claude/skills/, starting with the baseline kit.

  3. 3

    Reviews land

    Every PR (and every push to one) gets an inline review within ~2 minutes — comments cited by skill name, anchored at the exact line.

§ II — Specimens for your habitat

Skills are how Clud Bug knows your codebase.

Generic PR review tools evaluate your code against generic best practices. Clud Bug evaluates it against your standards — encoded as plain Markdown the bot loads on every PR. A few of the high-value patterns teams write:

Spec. brand-voice

Brand voice review

“Microcopy reviewed against the brand guide. Button labels follow verb-noun. Toasts ≤ 80 chars. No exclamation marks outside the success state.”

cat. № YOU-001
Spec. api-contract

API contract enforcement

“Anything under /v1/* is frozen. Schema changes need a /v2 alongside. Flag breaking changes; require deprecation headers on removals.”

cat. № YOU-002
Spec. compliance

Compliance & PII

“No PII (email, phone, name) in logs, ever. No console.log in app/api/*. Every secret read needs an audit log entry.”

cat. № YOU-003
Spec. test-discipline

Test discipline

“Every new endpoint ships a happy-path and a 4xx test in the same PR. Refactors can’t reduce test count without an explicit note.”

cat. № YOU-004
§ III — Three Naturalists

When one pair of eyes isn’t enough.

Most reviews are a single fast pass — skill-aware and cited. On the Team tier, Clud Bug runs a two-pass cross-check: a second naturalist re-reads the first one’s findings against the diff, and a third — the arbiter — is called in only when the two disagree:

Pass 1

Beetle

The broad scan. Walks the full diff, surfaces every candidate issue, no filtering. Optimized for recall.

Pass 2

Wasp

The cross-check. Re-reads Beetle’s findings against the diff and the skills, drops noise, escalates the real ones, and catches what Beetle missed.

Pass 3

Mantis

The arbiter. Only fires on disputes — where Beetle and Wasp disagree on severity or correctness. Returns a single decisive call with reasoning.

Three perspectives, one PR thread, citations all the way down. Compare tiers →

§ IV — Weight of Evidence

A finding carries the evidence that caught it.

Most review tools can only point at one suspicious line, so those are the only bugs they catch. Clud Bug grounds every finding one of three ways — a line quoted from the diff, a reproduction it actually runs, or a named invariant the change breaks. The reproduction is the sharp end: a real bug often lives on no single changed line.

That reaches three classes a line-scanner walks past. Emergent — bad data flowing through individually-correct lines, like a shared default mutated across calls. Combinatorial — an invariant broken only by a constructed input, like a duplicate key on a collision. Cross-cutting — a cause in another file the diff merely exposes, like a date-only sort read from a module the change never touched.

The measurement. On a seeded corpus of 20 scenarios — 14 planted defects across those three classes plus 6 clean look-alikes as precision controls, each scored by three independent reviewers — the hardened recipe caught every bug and false-flagged none: 100% recall, 100% precision, every catch grounded by a reproduction the reviewer wrote and ran.

§ V — Recorded Observation

From Clud Bug’s notebook.

Found all four planted bugs plus a fifth bonus problem (command injection via sh -c + rm -rf — worse than the SQL injection — RCE). Inline comments posted at each site.
Specimen review · 53 seconds · PR #2
§ VI — Field Economy

Even the largest specimens get a full examination.

Every PR review gets a budget tailored to its diff. Clud Bug looks at the changed lines first — a one-file typo gets a quick pass; a thousand-line refactor gets the time it needs. The bot is told its own budget upfront and checks in with itself mid-review, so the summary at the bottom of your PR is always a finished thought, never a half-written sentence.

Why this matters. Stock PR-review tools pick a fixed turn count and hope. On small PRs they overspend; on large PRs they run out and leave you with an incomplete review. The budget-aware approach: tiny PR gets ~5 turns of attention, large PR gets ~25, very large gets ~40 — same Clud Bug, same quality bar.

§ VII — Return Visit

Push a fix; the reviewer comes back to check it.

Every finding lands with a one-line fix. Push the change, and on the next commit Clud Bug re-reads each thread it opened — comparing the code at the anchor before and after — and decides, thread by thread, whether the concern was actually addressed.

A thread that was addressed resolves itself and says so. One that was not stays open, noted that the re-review still applies — and if it was critical, the check flips to request-changes. When the verdict is uncertain on a critical finding, the thread stays open and escalates: a critical is never silently dismissed. What was genuinely fixed clears out; what still matters stays pinned.

§ VIII — A Second Lens

For UI changes, an eye on the rendered page.

Code review reads the diff; it never sees the page. When a repo carries design skills — a house style, a spacing scale, a set of elite-UI standards — Clud Bug can open an optional visual pass. On a pull request with a live preview, it renders each changed surface in light and dark, then critiques the screenshots against those skills, citing the element it sees and the standard it reads against.

It flags what is fine but not elite, not only what is broken. The pass stays off until a repo asks for it, and stays advisory until it is told to gate — the render runs only on an opted-in Team repo, only on a pull request, only when a design skill is installed.

§ IX — Max Mode

The review runs in the session you already pay for.

The hosted App carries its own credentials and its own runner. Max mode carries neither: the review runs inside the Claude Code session already open on your machine, on the subscription you already have. A commit hook surfaces the review recipe; /clud-bug-review runs it on demand against the current branch’s open PR.

npx clud-bug init --with-hooks
  🐛 commit hook wired into .claude/settings.json
  reviews run on this session — no ANTHROPIC_API_KEY

git commit -m "Fix the parser"
  clud-bug review (max mode) — on your subscription
§ X — Self-hosted alternative

Prefer your own runner? Ship the workflow.

The hosted GitHub App is the recommended path — managed runner, managed billing, no secrets to rotate. For air-gapped orgs and teams that want to bring their own Anthropic key, the same review engine ships as an open-source npm package and runs as a GitHub Action under your own credentials.

npx clud-bug init
  🐛 Field season opens here.
    baseline kit: 4 specimens
  pinned 4 to .claude/skills/
  wrote .github/workflows/clud-bug-review.yml

git add .claude .github/workflows/
git commit -m "Add clud-bug" && git push