pr-review-dashboard

Files (5)

• SKILL.md
• diagram-selection.md · references/
• review-method.md · references/
• dashboard_template.html · scripts/
• validate_dashboard.py · scripts/

SKILL.md (first lines)

# PR Review Dashboard

Act as a staff-level code reviewer. Produce a decision aid that helps an unfamiliar reviewer understand the change, verify its safety, and know what to do next.

Put correctness, evidence, and actionable findings ahead of visual quantity. Use diagrams to compress relationships that prose cannot; do not use them as decoration. Do not modify the reviewed code, submit a GitHub review, or post comments unless the user explicitly asks.

Read [references/review-method.md](references/review-method.md) completely before evaluating the change. For any non-trivial PR, also read [references/diagram-selection.md](references/diagram-selection.md) completely before choosing visualizations.

## 1. Establish the review boundary

Run from the repository root and capture the local state before reviewing:

```bash
ROOT=$(git rev-parse --show-toplevel) || exit 1
cd "$ROOT"
CURRENT=$(git symbolic-ref --quiet --short HEAD || true)
HEAD_SHA=$(git rev-parse HEAD)
git status --short
```

Stop if `CURRENT` is empty: a detached `HEAD` does not identify a feature branch reliably. Record any working-tree changes. Review only committed `$BASE...HEAD` changes unless the user explicitly includes local changes; never silently attribute unrelated uncommitted work to the PR.

Discover and read applicable repository guidance before judging the code. Check root and changed-path scopes for `AGENTS.md`, `CONTRIBUTING*`, review guides, architecture docs, test instructions, and language-specific conventions. Prefer `rg --files` for discovery.

Fetch remote refs on a best-effort basis:

```bash
git fetch origin --quiet
```

If fetching fails, continue only when a usable local base ref exists. Disclose that remote freshness was not verified.

## 2. Resolve the PR and its actual base before diffing

Resolve author intent and the target branch before gathering the diff. A PR may target `develop`, a release branch, or another non-default branch; the repository default is only a fallback.

Use the following lookup ladder. Treat an error, empty string, `null`, or `[]` as no result and continue. The explicit `wtpr` breadcrumb is the only reliable recovery path for some fork PRs and merged/closed worktree PRs.

```bash
FIELDS=url,number,state,title,body,author,labels,additions,deletions,changedFiles,baseRefName,headRefName,headRefOid,headRepositoryOwner,isCrossRepository,isDraft,reviewDecision,mergeable,statusCheckRollup
PR_JSON=""

has_pr_result() {
  [ -n "$1" ] && [ "$1" != "null" ] && [ "$1" != "[]" ]
}

PR_NUM=$(git config "branch.$CURRENT.prNumber" 2>/dev/null || true)
if [ -n "$PR_NUM" ]; then
  PR_JSON=$(gh pr view "$PR_NUM" --json "$FIELDS" 2>/dev/null || true)
fi

if ! has_pr_result "$PR_JSON"; then
  PR_JSON=$(gh pr view --json "$FIELDS" 2>/dev/null || true)
fi

if ! has_pr_result "$PR_JSON"; then
  PR_JSON=$(gh pr list --head "$CURRENT" --state all --json "$FIELDS" 2>/dev/null || true)
fi
```

Sanity-check every candidate before trusting it:

- Require `headRefName` to match `CURRENT` unless the local branch name was intentionally rewritten.
- Prefer `headRefOid == HEAD_SHA`. Accept a newer remote head only when ancestry and PR context show it is the same work; otherwise disclose the mismatch or reject the candidate.
- Treat a repo-wide `branch.<name>.prNumber` as stale when the branch name was reused or the candidate describes different work.
- When a branch-name search returns several PRs, choose the matching head SHA, then the matching lineage, then the most recent only as a disclosed fallback.

If a PR resolves, use its `baseRefName` as `BASE_BRANCH`. Capture its URL, state, draft status, author, body, checks, review decision, and mergeability. If no PR resolves, determine the default branch:

```bash
BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
[ -z "$BASE_BRANCH" ] && git show-ref --verify --quiet refs/heads/main && BASE_BRANCH=main
[ -z "$BASE_BRANCH" ] && git show-ref --verify --quiet refs/heads/master && BASE_BRANCH=master
```

Stop if `BASE_BRANCH` is empty. Prefer `origin/$BASE_BRANCH`; fall back to the local branch only when necessary and disclose that choice.

```bash
BASE="origin/$BASE_BRANCH"
git rev-parse --verify "$BASE^{commit}" >/dev/null 2>&1 || BASE="$BASE_BRANCH"
git rev-parse --verify "$BASE^{commit}" >/dev/null 2>&1 || exit 1
MERGE_BASE=$(git merge-base "$BASE" HEAD)
COMMIT_COUNT=$(git rev-list --count "$BASE"..HEAD)
```

Stop when `COMMIT_COUNT` is zero. If `CURRENT` equals `BASE_BRANCH`, stop unless a resolved PR and commit comparison prove this is intentional.

Treat the PR body as the author's stated intent, never as ground truth. Record mismatches between the body, issue, commits, diff, tests, and documentation.

## 3. Gather the complete change surface

Use three-dot syntax for the PR diff and two-dot syntax for branch-only commits:

```bash
git diff "$BASE"...HEAD --stat
git diff "$BASE"...HEAD --shortstat
git diff "$BASE"...HEAD --name-status --find-renames --find-copies
git diff "$BASE"...HEAD --numstat --find-renames
git diff "$BASE"...HEAD --summary
git diff "$BASE"...HEAD --check
git log "$BASE"..HEAD --format='%h %s%n%b'
```

Distinguish final branch behavior from commit history. Use `git diff "$BASE"...HEAD` as the review ground truth; use individual commits only to recover rationale or spot risky intermediate/reverted work.

Load code in proportion to size:

- **Small** — at most 10 files and 500 changed lines: read the full final diff and every changed production/test file.
- **Medium** — at most 30 files and 3,000 changed lines: read the full final diff, then focus dashboard excerpts on the consequential paths.
- **Large** — over either threshold: start with stats and file groups, then inspect every changed production path and sample generated/vendor churn. Load targeted diffs and surrounding files rather than one enormous patch.

For all sizes, inspect relevant unchanged callers, callees, interfaces, schemas, configuration, and tests with `rg`, `git show "$MERGE_BASE:<path>"`, `git diff "$BASE"...HEAD -- <path>`, and the file at `HEAD`. Do not infer a symbol's behavior from its name.

When a GitHub PR is available, inspect existing check results, reviews, and unresolved review threads on a best-effort basis. Use them to avoid duplicate work and identify disputed assumptions, but verify claims independently. Do not post anything.

## 4. Perform an evidence-led review

Follow the mandatory review method. In particular:

From surajssd/dotfiles, MIT.

More from surajssd/dotfiles