pr-review

Files (3)

• RUBRIC.md
• SKILL.md
• evals.json · evals/

SKILL.md (first lines)

# GitHub PR Reviewer (`/pr-review`)

A disciplined, senior-grade code reviewer for GitHub Pull Requests and local Git
branches. Powered by the 13-angle evaluation rubric and the adversarial
**Inquisitor Doctrine ("Presumption of Theater")** in [`RUBRIC.md`](RUBRIC.md)
to purge hallucinatory AI fluff, pedantic theater, and unverified assumptions.

---

## 🎯 Primary Capabilities

1. **Explicit 3D Paranoia Tiering (`OQ3`)**: Computes Audience Ring
   (`Ring 0..4B`), Author Domain Confidence (`High|Low`), and Reversibility
   (`🚪 One-Way` vs. `🔄 Two-Way` Door) to select `Standard` (single-pass) or
   `Deep` (multi-subagent parallel) review mode.
2. **Two-Axis Evaluation (`Spec` vs. `Standards`)**: Verifies issue requirement
   traceability (`gh issue view <N>`) alongside `~/.agents/CODING_STANDARDS.md`
   and the 13-angle defect rubric in [`RUBRIC.md`](RUBRIC.md).
3. **Adversarial Inquisitor Gating & Clickable Permalinks**: Filters every
   candidate finding through the Five Inquisitorial Filters in
   [`RUBRIC.md`](RUBRIC.md) and links directly to GitHub source lines
   (`https://github.com/<owner>/<repo>/blob/<sha>/<file>#L<start>-L<end>`).
4. **2-Tier Ownership Action Gate (`OQ1`)**: Adapts `ask_question` defaults
   between owned `kevmoo/*` branches (auto-fix + `kscripts pr-check`) and
   external/peer PRs (strictly read-only local checkout).

---

## 🛠️ Execution Protocol

### Step 1: Pre-Flight Scope, Ownership & 3D Paranoia Classification

1. **Target & Ownership Detection (`OQ1`)**:
   - **Explicit PR (`#N` or URL)**:
     ```bash
     gh pr view <PR> --json author,headRepositoryOwner,headRepository,headRefName,baseRefName,headRefOid,number,title,body,url
     gh pr diff <PR>
     ```
   - **Local Branch / Worktree (no arguments)**:
     ```bash
     TARGET_BASE=$(git merge-base origin/main HEAD 2>/dev/null || git merge-base origin/master HEAD 2>/dev/null || git merge-base main HEAD)
     git diff ${TARGET_BASE}..HEAD
     gh pr view --json author,headRepositoryOwner,headRefName,number,title,url,headRefOid 2>/dev/null
     ```
   - Classify ownership into two tiers:
     - **Tier 1 (Own Repo `kevmoo/*` + Author `kevmoo` /
       `$(gh api user --jq .login)` with `headRefName` checked out locally, or
       local feature branch)**: Local remediation and test execution
       (`kscripts pr-check`) enabled.
     - **Tier 2 (External/Peer PR, non-`kevmoo` author, or PR branch not checked
       out locally)**: Strictly read-only local checkout.

2. **Linked Issue, Spec & Prior Review Thread Extraction (`FU1`)**:
   - When a PR links an issue (`Fixes #N`, `Closes #N`, or prompt issue URL),
     fetch the specification contract:
     ```bash
     gh issue view <N> --json title,body
     ```
   - On explicit PRs with prior review rounds, fetch existing review threads
     (resolved and unresolved) to respect settled design decisions and skip
     previously addressed feedback:
     ```bash
     gh api graphql -F owner='{owner}' -F name='{repo}' -F pr={pr_number} -f query='query($owner:String!, $name:String!, $pr:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$pr) { reviewThreads(first:100) { nodes { isResolved path line comments(first:10) { nodes { author { login } body } } } } } } }'
     ```

3. **3D Paranoia Header & Review Mode Selection (`OQ3`)**:
   - Always compute and render at the top of `pr_review_<PR>.md` and in visible
     chat:
     `🛡️ Paranoia Tier: Ring <0..4B> (<Label>) · Confidence: <High|Low> · Door: <🚪 One-Way | 🔄 Two-Way> -> Review Mode: <Standard | Deep>`
   - **Ring Defaults**:
     - **`Ring 0-2` (`kevmoo/*` personal dotfiles, skills, scripts)**: Default
       to `Review Mode: Standard` (single-pass review across the 13 angles)
       unless `--deep` / `--paranoid` is passed or `Door: 🚪 One-Way`.
     - **`Ring 3-4` (`kevmoo/*` published `pub.dev` packages, `dart-lang/*`,
       `flutter/*`, `google/*`, or low-confidence C++/VM/Wasm/Skwasm/WIMP
       domains) or `Door: 🚪 One-Way` (public API/wire/schema changes)**:
       Default to `Review Mode: Deep` (multi-subagent parallel angle audit +
       adversarial verification).
   - Support `--deep` (`--paranoid`) as an upfront flag to force
     `Review Mode: Deep` on any ring.

---

### Step 2: Two-Axis Grounding (`Spec` + `CODING_STANDARDS.md`)

Inspect complete modified files (`view_file`) along with callers and SDK/package
dependencies rather than diff hunks in isolation.

1. **Axis A — Spec & Issue Contract Traceability (`FU1`)**:
   - Cross-check every requirement in the linked issue (`gh issue view <N>`)
     against the implementation and test suite (`Met ✅`, `Partial ⚠️`,
     `Unmet ❌`, `Out-of-Scope ➖`). Flag unwired CLI flags or missing
     acceptance criteria.
2. **Axis B — Dart & Package Standards (`~/.agents/CODING_STANDARDS.md`)**:
   - Audit Dart diffs against `~/.agents/CODING_STANDARDS.md`:
     - **Deep Externally, Pure Internally**: Keep `lib/<pkg>.dart` and `api.txt`
       minimal, and use pure private functions (`_computeX(input) -> output`)
       for internal decomposition.
     - **Load-Bearing Library Boundary Rule**: Extract a standalone `lib/src/`
       library (`Tier 1`) only when zero `_private` visibility widening is
       needed; use `part` / `part of` (`Tier 2`) when crossing `sealed`,
       `final`, `interface`, `base`, `._()`, or `_private` class members so
       `_private` members stay library-scoped.
     - **Public API Surface Verification**: When refactors extract helpers
       across files, verify public API stability with
       `dart run api_summary@^1.1.0` (`--check` if `api.txt` exists, or
       before/after diff).

---

### Step 3: Adversarial Evaluation (`RUBRIC.md`)

1. **Sweep the 13 Angles in [`RUBRIC.md`](RUBRIC.md)**:
   - _1. Line Scan_ · _2. Removed Behavior_ · _3. Cross-File Tracer_ · _4.
     Language Pitfalls_ · _5. Invariants & Wrappers_ · _6. Error Handling_ · _7.
     Testing (Anti-Tautology & Public-Entrypoint Seams)_ · _8. Reuse_ · _9.
     Simplification_ · _10. Efficiency_ · _11. Altitude_ · _12. Readability &
     Conventions_ · _13. Cyclomatic Complexity_.
   - In `Review Mode: Deep`, run deterministic CLI verification (`dart format`,

From FMorschel/agents, MIT.

More from FMorschel/agents