pr-audit

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:

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.