run-by-experts

name

run-by-experts

description

Use before opening a SUBSTANTIVE PR (protocol changes, multi-tenant or auth surfaces, adopter-facing examples, refactors that span specialism modules). Fires multiple expert reviewers in parallel and uses convergence as the blocker signal — items flagged by 2+ reviewers are real; single-reviewer findings are usually preferences. Skip for trivial changes (single-line fixes, README typos, mechanical refactors).

Run by Experts

Overview

Multi-reviewer parallel review where convergence is the load-bearing signal. Items flagged by two or more reviewers are real blockers. Single-reviewer findings are usually preferences worth considering but not gating.

This skill exists because solo Claude review on a non-trivial PR catches obvious bugs but misses domain-specific landmines (multi-tenant isolation, protocol shape, type-system gotchas, adopter-DX cliffs). Each expert reviewer carries different domain priors; running them in parallel and acting on the intersection produces a better signal than any single review.

When to use

Always run before opening:

• Protocol-level changes (request/response shapes, error codes, new specialism interfaces)
• Multi-tenant or auth surfaces (isolation gates, credential handling, sandbox boundaries)
• Adopter-facing examples (examples/hello_*, skill files, public docs)
• Bug fixes where the root cause might be either side of an interface boundary

Optional but high-value:

• Refactors that span multiple specialism modules
• API surface changes (export shape, type changes, deprecations)
• New subagent prompts or skill files

Skip:

• Trivial changes (changesets, single-line bug fixes with obvious test coverage, README typos)
• Pure mechanical refactors (rename, dead-code removal) where you've verified no behavior change

The reviewer set

Pick the relevant subset for the PR. Default for a substantive change is all four:

Reviewer	Focus	Fire when
ad-tech-protocol-expert	Wire shape vs spec, error code placement, schema conformance, protocol contract	Any protocol-touching change
code-reviewer	Correctness, type-safety, dead code, casts, edge cases, hidden control flow	All non-trivial code changes
security-reviewer	Tenant isolation, auth/credential handling, prompt-injection surfaces, fail-open vs fail-closed gates, SSRF	Any change that touches auth, multi-tenancy, or buyer-supplied data flowing through error envelopes
dx-expert	Forkability, SWAP markers, header doc clarity, copy-paste anti-patterns, README discoverability	Any adopter-facing example or doc change

For protocol-only / spec-side changes, adtech-product-expert (buy-side / sell-side product fit) is often a fifth.

How to fire

Single message, multiple Agent tool calls in parallel — never sequential. Run-in-background unless the PR is so small that you'll wait on the first one. Each prompt is self-contained: the agent has no memory of the conversation, so include:

• File paths in scope
• Branch name
• Specific items the prior round (if any) claimed to fix — verify each
• Specific concerns you want flagged (don't ask "what do you think?" — that produces shallow review)
• Word budget ("Under 500 words")
• Format expectation ("Report: blockers / concerns / fine, per item")

Example brief shape (excerpted from bokelley/hello-adapters-gov-rights round 2):

Re-review of PR #XXXX. Prior round flagged 17 findings; all blockers + must-fix concerns claimed addressed. Verify, and flag any NEW issues introduced by the fixes.

Files in scope: examples/foo.ts (new, ~1200 lines).

Prior-round items that should be fixed — verify each:

1. ...
2. ...

New questions for this round:

1. ...

Report: blockers / suggestions / nits. Under 500 words. Don't restate prior-round findings unless the fix introduces a new issue.

Reading the results

Convergence (2+ reviewers same finding) = real blocker. Act on these unconditionally.

Single-reviewer must-fix = should-fix. Read the reasoning; usually it's worth doing but defensibly skippable. Push back if the finding contradicts the convergent signals.

Advisory = nice-to-have. Roll into a follow-up issue or comment-only fix.

The convergence signal is doing real work. From the production example (round 1 of the multi-tenant adapter PR):

• The as unknown as { account?: ... } cast was flagged by THREE of four reviewers (code: "may be reading a runtime-undefined field"; DX: "cargo-cult-bait"; protocol: implicitly endorsed by saying "should pull from ctx.account"). All three independently spotted that the cast was a real bug, not a style preference.
• Single-reviewer concerns were mostly preferences (helper extraction style, comment placement nits). Worth doing but not gating.

Two-round pattern

For substantive PRs, run two rounds:

1. Round 1 — initial review. Fire all relevant reviewers on the unreviewed code. Consolidate findings by convergence. Apply blockers + must-fix.
2. Round 2 — re-review of fixes. Fire the same reviewers again, asking each to (a) verify each prior-round finding is fixed and (b) flag any NEW issues the fix introduced.

Round-2 finds the regressions fix-blindness misses. Production example: round 2 caught a fail-OPEN tenant gate that round 1's fix had introduced (the gate was if (homeTenantId && tenantId !== homeTenantId) — when homeTenantId is undefined, the check skips; round 1 hadn't considered that path).

Process artifacts to ship with the PR

After all rounds land, the PR description should include:

• A consolidated "Expert review" section listing each round's blockers and how each was addressed
• The reviewer convergence signal (e.g., "3 of 4 flagged X" → "this was the real bug")
• Any single-reviewer items that were intentionally NOT fixed, with reasoning
• Cross-links to upstream-spec issues filed during review (if storyboards or spec gaps surfaced — see skills/triage-storyboard-failure/)

What this skill is NOT

• A replacement for human reviewers — convergent expert review surfaces issues fast, but humans make the final call on whether to merge
• An excuse to skip writing tests — reviewers can't verify behavior they can't run
• A substitute for npm run typecheck / npm run format:check / CI — those gate-before-review

See also

• skills/triage-storyboard-failure/ — when an expert review (or your own testing) surfaces a storyboard-vs-spec mismatch
• examples/CONTRIBUTING.md — the SWAP-marker and DO-NOT-DEPLOY-AS-IS conventions DX reviewers will check for
• ~/.claude/commands/prep-for-pr.md (personal command) — calls this skill plus the build/test/security-review chain