git:20261011.e174462 to git:20261011.7acf6e7

---

name: pr-review

argument-hint: "[base-branch | pull-request] | mine"

disable-model-invocation: true

---

# PR review

Slice the diff; for each slice, one agent maps the catalog onto its added lines and reviews every concern it mapped; a separate skeptic validates every finding. The report is compiled mechanically from validated findings only. Every agent runs on the model of the session that invoked the skill. It launches a multi-agent run, so it runs only when the user invokes it.

## Modes

- **Review** (default): the current branch against its base, or the named base branch or pull request.

- **Mine** (argument `mine`): build or refresh the project's concern catalog, per [references/mining.md](references/mining.md).

## Inputs

- **Settings first**: Read `.claude/shipyard/pr-review.md` in the project root, if it exists, before anything else. It sets the base branch, review paths, security-sensitive paths, slice size, agent cap, findings cap, and CI-enforced rules with their suppression markers; shape in [references/overlay-example.md](references/overlay-example.md).

- **The catalog**: every `references/catalog-*.md` (format in [references/catalog.md](references/catalog.md)) plus the project's `.claude/shipyard/pr-review/concerns.md`, which wins on id collisions.

- **The diff**, scoped once by `scope.sh` in this skill's folder and shared with every agent.

## Pipeline

```

scope.sh ──> full.diff + diff.txt ("path:line: code", added lines only)

│ slices: one if ≤ 10 files and ≤ 400 added lines; else ~400 lines each,

▼ by top-level directory, security paths alone, at most 6 (slices grow past it)

1 Map and review concern-reviewer per slice, in parallel, whole catalog each:

│ MAP concerns to its lines, then REVIEW each: finding or cleared

▼

check (no model) drop findings whose evidence_line isn't at location; flag unreviewed ids

▼

2 Validate review-verifier, one agent over every slice's findings:

│ confirmed | false-positive | pre-existing | duplicate

▼

report from confirmed findings only: Bugs / Issues / Nits / Summary + coverage

```

Contracts, schemas, the slicing rule, and the report template: [references/stages.md](references/stages.md). The runnable script: [references/workflow.js](references/workflow.js).

## Rules

- **Evidence line is mandatory.** Every finding cites `location` and `evidence_line` verbatim from `diff.txt`; the mechanical check drops any whose line isn't there.

- **Added lines only.** Pre-existing defects are tagged and dropped, not reported.

- **Severity**: `bug` wrong behavior, data loss, or a security hole; `issue` a design defect a reviewer would block on; `nit` a minor preference with a reason. Mark design-level findings as possibly intentional.

- **Findings cap** from settings (default 10), highest severity first; say how many were cut.

- **Don't re-flag what CI enforces**, except an added line that suppresses a rule.

- **Read-only end to end**: no agent edits files or commits. Posting findings as PR comments is a separate step and a **HUMAN TRIGGER**: only on the user's approval.

- **The coverage line reports what ran**: counts from agent outputs and the check, `n/a` for any not computed, never an estimate; unreviewed concerns are listed, never hidden. The verdict is advisory.

## Steps (review mode)

```

- [ ] 1 Read settings and resolve the base

- [ ] 2 Scope the diff

- [ ] 3 Run the two stages

- [ ] 4 Print the report

- [ ] 5 Offer rejected findings on request

```

1. **Read settings and resolve the base**: the settings' base branch, else the default branch; for a pull request, fetch its head into a worktree.

2. **Scope the diff**: `bash <skill>/scope.sh <worktree> <base> <scratch> [review paths, :!skips]`, or `--diff <file>` when you were handed a diff. It prints `files=N added=M`; on `added=0` report "No changes to review." and stop. Without a shell, build `diff.txt` from the diff yourself.

3. **Run the two stages**. With a workflow runner, run `references/workflow.js` with args `worktree`, `base`, `scratch`, `skillDir`, `diff` (the contents of `diff.txt`), `title`, `focus` (plus `cap`, `ciRules`, `securityPaths`, `sliceLines`, `maxAgents` from settings) and print its `report` verbatim. Without one, follow "Running without a workflow runner" in [references/stages.md](references/stages.md): `concern-reviewer` per slice (namespaced, e.g. `shipyard-delivery:concern-reviewer`) in parallel, the check, then `review-verifier`, each a direct child of this session.

4. **Print the report**: Bugs, Issues, Nits (each says `none` when empty, never omitted), then the Summary with the verdict and the coverage line.

5. **Offer rejected findings on request**: only if the user asks; they're the audit trail of what the check and validation killed.

## Handoff

`next:` fixes go back to the implement stage; a clean review goes to the describe stage.