pr-overview

What this skill does

# PR Overview

Fetch a GitHub PR, review it through multiple specialized agents (read-only), collect any unresolved comments, and produce a self-contained HTML overview at `pr-overview.html` in the repo root so the user can read it in a browser.

This skill never modifies code, never commits, never pushes, and never resolves comment threads. It only produces an overview. For a workflow that also applies fixes, use `pr-review-html`; for one that addresses reviewer comments, use `pr-review-fixer`.

## Phase 1: Fetch the PR

Resolve which PR to look at, in this order:
- An explicit number, URL, or branch name from the user
- Otherwise the PR for the current branch via `gh pr view --json number`

Pull what you need:
- `gh pr view <pr> --json number,title,author,baseRefName,headRefName,body,url,state,commits,files,createdAt`
- `gh pr diff <pr>` for the unified diff

Do **not** run `gh pr checkout`. This skill is read-only — the user may be on a different branch deliberately, and switching branches risks losing work. If the agents need code context beyond the diff, read files at the PR's `headRefName` via `gh api` rather than checking out.

Keep the PR `body`, `author`, `createdAt`, and `url` from the `gh pr view` JSON — these flow into Phase 6's `pr_description` section so the reader can see the author's framing verbatim.

Show the user which PR you're about to summarise (number, title, author, head → base, commit count) before doing the heavier work — a cheap sanity check that catches the wrong PR number early.

## Phase 2: Fetch unresolved comments

Use the same GraphQL query as `pr-review-fixer` to pull every code-level thread, PR-level review, and discussion comment:

```bash
gh api graphql -f query='
  query($owner: String!, $repo: String!, $pr: Int!) {
    repository(owner: $owner, name: $repo) {
      pullRequest(number: $pr) {
        reviewThreads(first: 100) {
          nodes {
            id isResolved url
            comments(first: 50) {
              nodes { id body author { login } path line createdAt url }
            }
          }
        }
        reviews(first: 50) {
          nodes { id body state author { login } createdAt url }
        }
        comments(first: 100) {
          nodes { id body author { login } createdAt url }
        }
      }
    }
  }
' -f owner=OWNER -f repo=REPO -F pr=$PR_NUM
```

A comment counts as a "Claude review" if **either** the author is `claude[bot]` (the upstream `anthropics/claude-code-action` Action) **or** the body contains the sentinel `<!-- claude-local-review -->` (emitted by the `local-review` agent when pr-pilot runs it locally). Treat both sources uniformly in the rules below.

Filter:
- **Code-level threads**: drop any thread where `isResolved: true`. For each remaining thread, surface the first comment as the top-level entry and any later comments as `replies`. If multiple Claude review comments exist in a thread, keep only the latest as the top-level entry.
- **PR-level reviews**: drop reviews with empty/whitespace bodies. Drop reviews where `state == "APPROVED"` and the body has no actionable feedback. For Claude reviews, keep only the most recent.
- **Discussion comments**: drop pure acknowledgements, CI bot noise, and `pr-review-fixer`'s "PR Review Overview" iteration reports (matched by the `<!-- pr-review-overview -->` sentinel or, for legacy comments, `claude[bot]` author + "PR Review Overview" in the body — they're already in the GitHub UI). For Claude reviews, keep only the latest.

Each surviving item becomes an entry in Phase 6's `unresolved_comments` array. Preserve the comment body **verbatim** — don't rewrite, summarise, or "clean up" reviewer markdown.

If there are no unresolved comments, the section is simply omitted from the output. Don't fabricate one.

## Phase 3: Locate the spec (if any)

Phase 4 review and Phase 5 explanation are both richer when grounded in the design intent, so look for a matching feature spec.

- Use the PR head branch name and title as hints
- Search `specs/` for a folder matching that feature
- If found, read requirements, design, tasks, and decision log
- If not found, skip spec-aware checks and continue

## Phase 4: Launch review agents in parallel (read-only)

Spawn all agents in a single message so they run concurrently. Pass each one the full diff — they need complete context to spot cross-file issues. Each agent **reports** findings only; nothing is fixed.

### Agent 1 — Code reuse

For each change:
- Grep for existing utilities, helpers, and similar patterns. Common locations: utility directories, shared modules, files adjacent to the changes.
- Flag any new function that duplicates existing functionality, and point at the existing one.
- Flag inline logic that could use an existing utility — hand-rolled string manipulation, manual path handling, ad-hoc type guards, custom env checks.

### Agent 2 — Code quality

Look for hacky patterns:
- Redundant state (duplicates existing state, cached values that could be derived, observers that could be direct calls)
- Parameter sprawl (new params bolted onto a function instead of restructuring it)
- Copy-paste with slight variation (near-duplicates that should share an abstraction)
- Leaky abstractions (exposing internals or breaking existing boundaries)
- Stringly-typed code where existing constants, enums, or branded types would fit

### Agent 3 — Efficiency

Look for waste:
- Redundant computations, repeated reads, duplicate API calls, N+1 patterns
- Independent operations run sequentially that could run in parallel
- New blocking work added to startup or per-request hot paths
- Pre-checking file/resource existence before operating (TOCTOU anti-pattern)
- Unbounded data structures, missing cleanup, listener leaks
- Reading whole files when a slice would do, loading everything when filtering for one

### Agent 4 — Spec & docs (only if a spec was found)

- Implementation matches requirements and design; divergences are documented in the decision log
- README, CLAUDE.md, or related docs need updates to reflect the changes
- Tests exist for new/modified behavior and test behavior, not implementation details

Aggregate the findings. Every finding's `status` is `"raised"` in the output — there are no `"fixed"` entries in this skill. Skip false positives and trivial style nits.

## Phase 5: Implementation explanation and insight material

Invoke the `explain-like` skill (Skill tool with `skill="explain-like"`) to produce all three expertise levels — Beginner, Intermediate, Expert. Keep the explanation in memory for the HTML output. Do **not** write it to `specs/{feature_name}/implementation.md` — this skill doesn't modify the repo.

Use the explanation as a validation pass:
- Anything in the spec that can't be cleanly explained → flag as potentially incomplete
- Anything in the explanation that diverges from the design → flag the divergence
- Add a "Completeness Assessment" with what's fully implemented, partially implemented, and missing

In the same pass, extract three pieces of structured content from the diff, commit messages, PR description/body, and (if present) the decision log. This feeds Phase 6 and must be produced even when no spec exists:

1. **Important changes** — the 3–7 commits or hunks that matter most for a reviewer. For each: a one-line title (file or area + verb), why it matters (correctness, performance, API surface, user-visible behaviour, security), and the specific line range or symbol.
2. **Learnings** — patterns, idioms, or APIs introduced in this PR that a reader could reuse elsewhere. One short "takeaway" per item, with a pointer to the example in the diff. Skip pure mechanical changes.
3. **Decision rationale** — for each non-trivial choice, capture the reason. Source order: (a) decision log entries that match the PR, (b) PR description, (c) commit message bodies, (d) inline code comments added in the diff, (e) inferred from the diff. Mark inferred entries explicitly as `inf