---
name: pstack-brief
preamble-tier: 3
version: 0.3.0
description: |
  Reviewer-side AI brief on a PR. Summarizes the change, flags risk areas,
  matches against anti-patterns. Reduces reviewer context-load cost. Uses
  GitHub MCP — works from Claude Desktop or Claude Code without `gh` CLI.
  Use when asked to "review brief", "/pstack-brief", "brief me on PR".
triggers:
  - /pstack-brief
  - review brief
  - brief me on PR
allowed-tools:
  - Bash
  - Read
  - Grep
---

# pstack-brief

Generate a 60-second briefing for a reviewer via GitHub MCP.

**Requires GitHub MCP server**. `Bash` stays in allowed-tools for the
optional GitNexus integration (local helper scripts), not for `gh`.

## Args

`/pstack-brief <pr-url-or-number>`

## Steps

### 1. Determine repo target

- **Claude Code with a local repo:** parse `owner/repo` from `git remote get-url origin`.
- **Otherwise:** parse from the PR URL if provided in `owner/repo#N` form, or ask the user.

### 2. Fetch PR metadata and diff via MCP

Call **`mcp__github__pull_request_read`** with:
- owner / repo: from Step 1
- pull_number: from the args
- include: PR metadata (title, body, base/head refs, additions/deletions, changed files list)
- include the diff (per-file or unified, whichever the tool offers)

If the tool's response doesn't include a full diff inline, fetch changed
files via `mcp__github__get_file_contents` for the most-relevant ones
(largest deltas, files matching the spec's "Files likely to touch").

### 3. Read linked context via MCP

From the PR body, extract:
- **Closes #N** → `mcp__github__issue_read` to fetch the story / issue
- **Parent Epic: #M** (from issue body) → `mcp__github__issue_read` to fetch the Epic body (which contains the drafty spec, OR the frozen spec lives in `docs/specs/<name>.md` if PR #C-equivalent freeze has run)
- **Vision** (from CLAUDE.md or Epic body) → `mcp__github__issue_read` for strategic context if linked

If `docs/specs/<name>.md` is in the diff (the freeze commit), read it
locally — it's the canonical spec for what was built.

### 4. Generate brief

Output format:

```markdown
# PR Brief: #<N> — <title>

## Summary (5 bullets)
- {{change 1}}
- {{change 2}}
- ...

## Risk areas (focus reading here)
1. **{{area 1}}** — {{why risky, file:line}}
2. **{{area 2}}** — {{why risky, file:line}}
3. **{{area 3}}** — {{why risky, file:line}}

## Anti-pattern matches
{{list of docs/anti-patterns.md entries that look related, or "none"}}

## Spec alignment
- Acceptance criteria covered: {{checked-off-list}}
- Acceptance criteria NOT visible in diff: {{warning-list}}

## Suggested time
- Critical reading: {{N}} min ({{file paths}})
- Skim: {{N}} min ({{file paths}})
```

### 5. Print

Output the brief. Do not post as a PR comment automatically (deferred —
see IDEAS.md "Reviewer-side AI summarization tied into PR description").

When that lands, the skill will use `mcp__github__add_comment_to_pending_review`
or `mcp__github__add_reply_to_pull_request_comment` to post inline.

## GitNexus integration

In Step 4 (Risk areas), weight risk by inbound caller count when GitNexus
is running locally:

```bash
if GITNEXUS=$(${CLAUDE_SKILL_DIR}/../../scripts/gitnexus-check.sh); then
  for file in $CHANGED_FILES; do
    CALLERS=$(${CLAUDE_SKILL_DIR}/../../scripts/gitnexus-query.sh callers "$file" 2>/dev/null | wc -l | tr -d ' ')
    # Files with >10 callers are high blast radius
  done
fi
```

In the "Risk areas" section, prefix high-coupling files with `⚠ high coupling ({N} callers)` so the reviewer focuses there first.

GitNexus runs locally — it's only available in Claude Code with the helper
scripts present. In Claude Desktop, skip this step and fall back to
file-size and diff-size heuristics for risk weighting.

## Do not

- Do not call `gh` CLI — use GitHub MCP.
- Do not approve or request changes from this skill.
- Do not modify the PR.