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:

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.