pr-audit

name	pr-audit
description	Multi-agent PR review — component, integration, and routing analysis merged into a structured audit doc with severity and PR buckets.
disable-model-invocation	false
user-invocable	true
argument-hint	[base-branch (default: dev)]

PR Audit

You run a multi-pass review of the current branch, pull in external PR feedback, and produce a structured audit document with findings grouped into PR-sized fix buckets.

This skill stops at the audit doc. It does not create issues or specs — use /gaps-to-issues and /spec-from-audit for those steps.

Input

$ARGUMENTS — Optional base branch name (default: dev).

Workflow

Step 1: Gather the Diff

Use $ARGUMENTS if provided, otherwise default to dev.

Verify the base branch exists:

git rev-parse --verify <base-branch>

If it does not exist, ask the user which branch to diff against.

Gather the full diff and context:

git log <base-branch>..HEAD --oneline --no-decorate
git diff <base-branch>...HEAD --stat
git diff <base-branch>...HEAD
git diff <base-branch>...HEAD --name-only
git status -s

Read the full diff carefully. You will reference it throughout the review passes.

Step 2: Multi-Agent Review (3 Parallel Passes)

Run all three review passes in parallel using the Agent tool. Each agent receives the diff context and reviews through a specific lens.

Pass A: Component-Level Review

For every new or changed screen/component file, check:

• Missing or incorrect imports (especially cross-package imports that don't resolve)
• Wrong or missing props vs the component's actual interface — read the component definition, don't guess
• Missing Lottie/animation assets or props that the component supports but aren't passed
• Placeholder logic left in production code (hardcoded values, no-op callbacks, TODO/FIXME)
• Missing error/loading/empty states
• Raw hex colors instead of design tokens
• Files exceeding 800 LOC

Pass B: Integration-Level Review

For the full set of changed files, check:

• Provider/contract flow violations — does data flow match what specs define?
• State propagation between screens — is state passed correctly through navigation, or lost on refresh/direct-entry?
• Persistence gaps — state that should survive reload but only lives in useState
• Event ordering issues — race conditions, guards that swallow later events
• Breaking changes to shared interfaces consumed by other packages
• Build-time vs runtime config that should be dynamic

Pass C: Route Wiring Review

For all navigation-related changes, check:

• Every navigate() / push() / replace() target has a corresponding route definition
• Every new route definition is reachable from at least one navigation call
• Orphaned routes — defined but unreachable
• Screens that receive location.state but have no guard for direct-entry (missing state)
• Deep link configuration consistency (if applicable)

Step 3: Pull in PR Feedback

Check if a PR exists for this branch:

gh pr view --json number,url 2>/dev/null

If a PR exists, fetch external review comments:

gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate
gh api repos/{owner}/{repo}/pulls/{number}/reviews --paginate
gh api repos/{owner}/{repo}/issues/{number}/comments --paginate

Extract actionable items from CodeRabbit, Codex, and human reviewers. Ignore resolved conversations and pure acknowledgment comments.

If no PR exists, skip this step.

Step 4: Merge and Deduplicate

Combine findings from all three passes and PR feedback. Deduplicate — if Pass A and a CodeRabbit comment flag the same issue, keep one entry and note both sources.

Assign severity:

Severity	Criteria
Critical	Build-breaking, crashes, data loss, security holes, blocked user flows
High	Incorrect behavior visible to users, contract violations, missing error handling on critical paths
Medium	Missing states, prop mismatches, design token violations, placeholder logic
Low	Style, minor code quality, non-blocking TODOs

Step 5: Group into PR-Sized Buckets

Group findings into fix buckets. Each bucket:

• Targets ≤2,000 LOC changed
• Groups related findings touching the same files or logical area
• Is independently mergeable (note dependencies if unavoidable)
• Has a clear name, estimated LOC, list of files, and acceptance criteria

Step 6: Write the Audit Document

Determine the branch slug from the current branch name (strip feat/, fix/, etc., replace / with -).

Create the audit document at:

docs/reviews/YYYY-MM-DD-<branch-slug>-audit.md

Create docs/reviews/ if it does not exist.

Structure:

# PR Audit — <branch-name>

> Date: YYYY-MM-DD
> Branch: `<branch-name>`
> Base: `<base-branch>`
> PR: #NNN (if exists)
> Reviewers: Claude Code (component, integration, routing passes), [external reviewers]
> Status: Audit complete — ready for review

## Summary

[2-3 sentences describing what the branch does and the overall health assessment.]

## Findings

### Critical

- [ ] [finding] — `path/to/file.ts:NN`
  - **Source:** [Pass A | Pass B | Pass C | CodeRabbit | reviewer]
  - **Fix:** [concrete action]

### High

- [ ] ...

### Medium

- [ ] ...

### Low

- [ ] ...

## PR Buckets

### Bucket 1: [name]
- **Estimated LOC:** ~NNN
- **Findings:** #1, #3, #7
- **Files:** [list]
- **Dependencies:** [none | Bucket N must land first]
- **Acceptance criteria:**
  - [ ] [criterion]

### Bucket 2: [name]
...

## What Works Well

[List things the branch does correctly — not just problems.]

Step 7: Present to User

Show the user:

1. Total finding count by severity
2. Each bucket with name, estimated LOC, and findings covered
3. Any findings that didn't fit cleanly into a bucket

Tell the user:

"Audit complete. Review the findings and buckets above. When ready, use /gaps-to-issues to create Linear issues from these buckets, then /spec-from-audit to generate specs."

Stop here. Do not create issues or specs.

Important Notes

• Never run git commit or git push. Stage the audit doc but stop there.
• Read the full diff — do not summarize from file names alone.
• Findings must be specific and actionable with file paths and line numbers.
• When estimating LOC for buckets, be conservative.
• If the diff is very large (>10k LOC), warn the user and suggest focusing on critical/high only.