---
name: pr-summary
description: Analyze all PR changes and update PR description with accurate summary.
allowed-tools: Read, Write, Bash, Grep, Glob
---

## Preamble

```bash
eval "$(~/.vibestack/bin/vibe-slug 2>/dev/null)" 2>/dev/null || SLUG="unknown"
_LEARN_FILE="${VIBESTACK_HOME:-$HOME/.vibestack}/projects/${SLUG:-unknown}/learnings.jsonl"
if [ -f "$_LEARN_FILE" ]; then
  _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ')
  echo "LEARNINGS: $_LEARN_COUNT entries loaded"
  if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
    ~/.vibestack/bin/vibe-learnings-search --limit 5 2>/dev/null || true
  fi
else
  echo "LEARNINGS: none yet"
fi
```

{{include lib/snippets/session-host.md}}

{{include lib/snippets/working-protocols.md}}

{{include lib/snippets/state-protocols.md}}

# PR Summary Update

## Philosophy

- **Analyze all changes without exception** — track all commits included in the PR, not just the latest.
- **Accuracy is essential** — do not guess; read the actual diff and code before describing.
- **Write from the reviewer's perspective** — explain "why" this change was needed and what impact it has.

## Rules

- Read all changed files before writing the summary
- Analyze ALL commits in the PR, not just the latest
- Be precise — do not guess or hallucinate changes
- Preserve existing PR metadata (labels, assignees, reviewers)
- Do NOT add promotional or attribution footers
- Do NOT add unnecessary lines (Co-Authored-By, Generated with, etc.)

## Process

### Step 1: Identify PR

Determine the PR number from argument or current branch:

```bash
# If argument provided, use it directly
PR_NUMBER={argument}

# Otherwise, infer from current branch
gh pr view --json number -q '.number'
```

### Step 2: Gather PR Context

```bash
# Get current PR details
gh pr view {PR_NUMBER} --json title,body,baseRefName,headRefName,commits,files

# Get base branch
BASE_BRANCH=$(gh pr view {PR_NUMBER} --json baseRefName -q '.baseRefName')

# View all commits in PR
gh pr view {PR_NUMBER} --json commits -q '.commits[] | "\(.oid[:7]) \(.messageHeadline)"'

# View all changed files with stats
gh pr diff {PR_NUMBER} --stat

# View full diff
gh pr diff {PR_NUMBER}
```

### Step 3: Analyze Existing PR Body

**CRITICAL: Check the existing PR body first.**

```bash
# Get current PR body
EXISTING_BODY=$(gh pr view {PR_NUMBER} --json body -q '.body')
```

**Check for user-added content to preserve:**
- Manual notes or context added by the author
- Links to related issues, designs, or discussions
- Sections not generated by this skill (e.g., custom sections)

If the existing body contains user-added content, preserve it in a `## Notes` section at the bottom.

### Step 4: Deep Analysis

**CRITICAL: Do not rely on diff statistics alone — understand the meaning of the changes.**

**For large PRs (>20 files or >1000 lines changed):**
- Group files by directory/module and analyze each group
- Focus on structural changes first, then detail changes
- Summarize at module level, not file level

**For each changed file:**
1. **Read the full diff** — understand what was added, modified, removed
2. **Read the file** — understand the full context around the changes
3. **Identify the purpose** — why was this file changed?
4. **Assess impact** — what depends on this? Could this break anything?

**Categorize changes:**

| Category | Description |
|----------|-------------|
| **New Feature** | New functionality added |
| **Bug Fix** | Existing behavior corrected |
| **Refactor** | Code restructured without behavior change |
| **Performance** | Optimization improvements |
| **Documentation** | Docs, comments, README updates |
| **Test** | Test additions or modifications |
| **Configuration** | Config, CI/CD, build changes |
| **Dependency** | Package additions, updates, removals |
| **Breaking Change** | Changes that break existing API/behavior |

**Deliberation questions:**
- What is the **single purpose** of this PR?
- Are there **breaking changes** for consumers?
- What **edge cases** might be affected?
- Are there any **risks** or **known limitations**?

### Step 5: Craft PR Summary

**Before writing, articulate:**
1. What problem does this PR solve? (Summary)
2. What specific changes were made and why? (Changes)
3. Are there any breaking changes? (Breaking Changes)
4. How should a reviewer verify this works? (Test Plan)

**PR body format:**

```markdown
## Summary
- Brief description of what and WHY

## Changes
- Change 1: why this was needed
- Change 2: why this was needed

## Breaking Changes
- (if any) Description of breaking change and migration path

## Test Plan
- [ ] How to verify changes work
- [ ] Edge cases to test
```

### Step 6: Update PR Description

The body quotes commit messages, diff content and the existing PR text, so it
never appears in shell source — not in a quoted argument, and not in a heredoc
either: a line equal to the terminator ends the heredoc and everything after it
runs as shell. Create a private file for it:

```bash
PR_BODY_FILE=$(mktemp "${TMPDIR:-/tmp}/vibe-pr-summary-XXXXXXXX")
echo "PR_BODY_FILE: $PR_BODY_FILE"
```

Read the empty file, then **Write the body into the printed `PR_BODY_FILE` with the
Write tool**, in the Step 5 format with every section filled from the analysis
(omit Breaking Changes when there are none). Then publish that file, substituting
the printed path and the PR number:

```bash
PR_BODY_FILE='<PR_BODY_FILE>'
[ -s "$PR_BODY_FILE" ] || { echo "ABORT: $PR_BODY_FILE is empty — write the body with the Write tool first" >&2; exit 1; }
gh pr edit {PR_NUMBER} --body-file "$PR_BODY_FILE" && rm -f "$PR_BODY_FILE"
```

### Step 7: Verify Update

```bash
# Confirm PR was updated
gh pr view {PR_NUMBER} --json title,body -q '.body'
```

### Step 8: Report Summary

```
## PR Summary Updated

**PR**: #{PR_NUMBER}
**Title**: {title}
**Base**: {base_branch} ← {head_branch}

### Analysis
- Total commits: {N}
- Files changed: {N}
- Lines added: +{N}
- Lines removed: -{N}

### Categories
- feat: {N} changes
- fix: {N} changes
- refactor: {N} changes
- ...

PR description updated successfully.
```

## Title Update

If the PR title is vague (e.g., "update", "fix", "WIP"), suggest a better title:

```bash
gh pr edit {PR_NUMBER} --title "<type>(<scope>): <subject>"
```

> **Note:** PR title optionally uses scope. Commit messages use `<type>: <subject>` format without scope.

**Only suggest title changes when:**
- Title is clearly vague or inaccurate
- Title doesn't reflect the actual changes
- Ask user before changing the title

## Anti-Patterns

- Do NOT write a summary without reading ALL changed files
- Do NOT rely only on commit messages — verify against actual diff
- Do NOT include changes that don't exist in the PR
- Do NOT use vague descriptions like "various improvements"
- Do NOT overwrite existing PR body without analyzing it first
- Do NOT skip reading file context — diffs alone can be misleading
- Do NOT add information that isn't supported by the code changes

---

## Capture Learnings

If you discovered a non-obvious pattern, pitfall, or insight during this session, log it:

```bash
~/.vibestack/bin/vibe-learnings-log '{"skill":"pr-summary","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
```

**Types:** `pattern`, `pitfall`, `preference`, `architecture`, `operational`.

**Only log genuine discoveries.**