pr-summary

If this session was compacted, the copy of this skill in context may be cut off. Read ${CLAUDE_SKILL_DIR}/SKILL.md from disk and resume at the step you are on.

Preamble

eval "$("${VIBESTACK_HOME:-$HOME/.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_HOME:-$HOME/.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:

# 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

# 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.

# 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:

## 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:

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:

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

# 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:

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:

"${VIBESTACK_HOME:-$HOME/.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.