gh-pr

# GitHub PR Communication Skill

Use this skill for creating, updating, or commenting on GitHub pull requests. Focus on material impact, safe operations, and respecting busy reviewers.

## When to Use This Skill

- Creating PRs from feature branches
- Updating PR descriptions after significant changes
- Adding comments to communicate with reviewers
- Any PR communication task

## Announcement

Always announce at start:

```
"I'm using the gh-pr skill to <create|update|comment on> the pull request."
```

## Core Principles

1. **Safety first:** All PR bodies written to `.scratch/pr-bodies/` before use with `gh --body-file`
2. **Material impact:** Focus on why changes matter, not metrics or file counts
3. **Smart merge:** Detect manual edits, only update when changes are material
4. **Human-friendly:** Concise, warm tone; assume busy reviewer
5. **Flexible workflow:** Explicit commands when clear, smart routing when ambiguous

## File Structure

```
.scratch/pr-bodies/
  drafts/
    <slugified-title>.md          # Draft body before PR creation
  <pr-number>/
    metadata.json                  # PR metadata and state
    <timestamp>-body.md           # Timestamped snapshots of generated bodies
    <timestamp>-comment.md        # Comment drafts
```

### Metadata Schema

```json
{
  "pr_number": 123,
  "branch": "feature/add-skill",
  "base": "main",
  "title": "Add spotlight exclusion skill",
  "created_at": "2025-11-07T10:30:00Z",
  "last_generated_hash": "abc123def456",
  "last_updated_at": "2025-11-07T16:45:30Z",
  "manual_edits_detected": false
}
```

## Trigger Patterns

### Explicit Triggers (Always Honored)

- **"create a PR"** / **"open a PR"** → Create flow
- **"update the PR body/description"** → Update body flow
- **"comment on the PR"** / **"add a PR comment"** → Comment flow

### Ambiguous Triggers (Smart Routing)

**"update the PR":**

- No PR exists → Error: "No PR found for this branch. Did you mean to create one?"
- PR exists, no reviews → Update body
- PR exists, has reviews → Ask: "This PR has reviews. Update body or add comment?"

**"communicate the changes":**

- PR exists, no reviews yet → Update body
- PR exists, has reviews → Add comment (generates notifications)

## Operation Flows

### 1. Create PR

```
☐ Check if PR already exists
  - gh pr view --json number 2>/dev/null
  - If exists → error or route to update

☐ Gather information
  - Commits: git log <base>..HEAD
  - Check for PR template (.github/pull_request_template.md, etc.)
  - Check for CONTRIBUTING.md
  - Analyze commit messages and diffs

☐ Generate PR content
  - Title: from branch name or first commit (imperative mood, <72 chars)
  - Body:
    * Follow template structure if exists
    * Summary: 2-4 bullets of material impact
    * Test plan: if non-obvious
    * NO H1 heading (GitHub shows title separately)
    * NO metrics (# tests, # files, etc.)
    * Concise, warm tone

☐ Draft review
  - Write to .scratch/pr-bodies/drafts/<slug>.md
  - Show draft to user: "Here's the draft PR. Does this look good?"
  - Allow edits before creating

☐ Create PR
  - gh pr create --title "..." --body-file .scratch/pr-bodies/drafts/<slug>.md
  - Capture PR number from output

☐ Archive and track
  - mkdir -p .scratch/pr-bodies/<number>/
  - mv draft to <number>/<timestamp>-body.md
  - Write metadata.json with hash of generated body
  - rm .scratch/pr-bodies/drafts/<slug>.md
```

### 2. Update PR Body

```
☐ Verify PR exists
  - gh pr view --json number,body,title,state
  - Load metadata.json if exists
  - Check state (error if closed/merged unless user confirms)

☐ Detect manual edits
  - Hash current body: echo "$body" | shasum -a 256
  - Compare to last_generated_hash in metadata
  - If differs:
    * Compute diff: diff <(echo "$last_generated") <(echo "$current")
    * Analyze: whitespace-only vs content changes
    * If material: show diff, ask "Overwrite manual edits, merge, or cancel?"

☐ Check for material changes
  - Re-analyze full commit range: <base>..HEAD
  - Compare to previous analysis
  - If no material change:
    * "The current PR description is still accurate."
    * Skip update unless user forces

☐ Generate updated body
  - Follow same content guidelines as create
  - Re-analyze all commits in range

☐ Draft review
  - Write to .scratch/pr-bodies/<number>/<timestamp>-body.md
  - Show diff: current vs proposed
  - "Here's what would change. Look good?"

☐ Update PR
  - gh pr edit <number> --body-file <file>
  - Update metadata.json (hash, timestamp, manual_edits_detected)
```

### 3. Add PR Comment

```
☐ Verify PR exists
  - gh pr view --json number,title,reviews,comments
  - Check for review activity

☐ Determine comment content
  - Analyze recent commits since last update
  - Focus on: what changed and why
  - Common scenarios:
    * Responding to review feedback
    * Noting significant additions after initial review
    * Summarizing a batch of changes

☐ Draft comment
  - Write to .scratch/pr-bodies/<number>/<timestamp>-comment.md
  - Tone: conversational, helpful, concise (3-5 sentences)
  - Structure: "I've updated the PR to address..."
  - Show draft to user

☐ Post comment
  - gh pr comment <number> --body-file <file>
  - Optional: Update metadata.json with comment timestamp
```

## Decision Matrix: Update Body vs Comment

**Prefer UPDATE BODY when:**

- PR has no reviews/comments yet
- User explicitly says "update description/body"
- Material scope change that needs description rewrite

**Prefer COMMENT when:**

- PR has review activity (comments, requested changes)
- User mentions "responding to feedback"
- Batch of changes after initial review
- Want to notify watchers (comments generate notifications, body updates don't)

## Content Guidelines

### PR Title Format

- **Imperative mood:** "Add", "Fix", "Update", "Refactor"
- **Concise:** < 72 characters ideal
- **Capitalize** first word
- **No period** at end
- **Derive from:** Branch name (if semantic) or first commit message

### PR Body Structure

**When PR template exists:**

- Follow template structure exactly
- Fill sections based on commit analysis
- Preserve template comments/instructions

**When no template exists:**

```markdown
## Summary

- Material impact point 1
- Material impact point 2
- Material impact point 3 (if needed)

## Test plan

- How to verify the changes work
- Only if non-obvious or requires manual testing

[Optional sections based on context:]

## Breaking changes

## Migration notes

## Follow-up work
```

### Content Principles

**✅ DO:**

- Focus on material impact: "Enables pattern-based Spotlight exclusions for easier maintenance"
- Be concise yet warm: "This makes it easier to manage exclusions at scale."
- Explain why it matters, what problem it solves
- Include non-obvious testing steps

**❌ DON'T - Common Anti-Patterns:**

**Metrics (unless PR is specifically about them):**
- ❌ "Added 15 tests" → ✅ "Added test coverage for edge cases"
- ❌ "Modified 8 files across 3 modules" → ✅ Say nothing (diff shows this)
- ❌ "Reduced runtime from 2.5s to 1.2s" → ✅ Only if PR is about performance
- ❌ "Added 250 lines of code" → ✅ Never mention line counts
- ❌ "Test coverage increased to 85%" → ✅ Only if PR is about coverage

**Implementation details visible in diff:**
- ❌ "Created new `PatternExpander` class" → ✅ Say nothing (diff shows this)
- ❌ "Refactored into smaller functions" → ✅ Say nothing unless it's the PR's focus
- ❌ "Used async/await pattern" → ✅ Say nothing (implementation detail)
- ❌ "Added error handling" → ✅ Only if error handling is the PR's focus

**Over-explaining/verbose:**
- ❌ "This change significantly improves the developer experience by implementing a novel approach..."
- ✅ "Makes it easier to maintain exclusions at scale"
- ❌ "After careful consideration of multiple approaches, we decided to..."
- ✅ Just describe what it does and why it matters

**Other common mistakes:**
- ❌ Use H1 heading (GitHub shows title separately, causes duplication)
- ❌ List technologies used unless it's a new dependency worth noting
- ❌ Describe file structure changes unless it's an architectural shift
- ❌ Mention "following best practices" (assumed)
- ❌ Say "easy to" or "simple to" (condescending)

**The rule:** If a reviewer can see it in the diff or CI output, don't put it in the PR body unless it's the central focus of the PR.

### Following Repository Guidelines

**Search for PR templates:**

```
- .github/pull_request_template.md
- .github/PULL_REQUEST_TEMPLATE.md
- .github/PULL_REQUEST_TEMPLATE/*.md
```

**Search for CONTRIBUTING.md:**

```
- CONTRIBUTING.md
- .github/CONTRIBUTING.md
- docs/CONTRIBUTING.md
```

**If found:** Extract PR-related guidance (required info, checklists, style) and incorporate into body generation.

### Comment Content Guidelines

**Structure:**

```markdown
I've updated the PR to address the feedback:

- Point about what changed
- Another significant change
- Why these changes were made

[Optional: specific response to review comment if relevant]
```

**Tone:**

- Conversational but professional
- Acknowledge reviewers' input
- Explain reasoning when non-obvious
- Keep brief (3-5 sentences typical)

## Error Handling & Edge Cases

### Safety Checks

**Before creating PR:**

- ✓ Current branch is not main/master
- ✓ Branch has commits ahead of base
- ✓ gh CLI is installed and authenticated
- ✓ User has reviewed draft

**Before updating PR body:**

- ✓ PR exists and is open (warn if closed/merged)
- ✓ Manual edits check complete
- ✓ User has reviewed diff

**Before posting comment:**

- ✓ PR exists
- ✓ Comment is not empty
- ✓ User has reviewed content

### Common Errors

**No PR exists (when updating/commenting):**

```
Error: "No PR found for branch '<branch-name>'.
Would you like to create one?"

Action: Offer to route to create flow
```

**Multiple PRs for branch:**

```
1. gh pr list --head <branch> --state open
2. If exactly 1 open PR → use it
3. If 0 open PRs:
   - Check: gh pr list --head <branch> --state all
   - "No open PR found. Last PR was #123 (closed/merged)."
   - Offer to create new PR
4. If >1 open PR (rare):
   - "Found multiple open PRs: #123, #456. Which one?"
```

**Not on a branch / on main:**

```
Error: "Currently on '<branch>'.
PRs should be created from feature branches, not main/master."

Action: Stop, suggest creating a branch first
```

**gh CLI not available:**

```
Error: "GitHub CLI (gh) not found. Install with: brew install gh"
```

**gh not authenticated:**

```
Error: "GitHub CLI not authenticated. Run: gh auth login"
```

### Edge Cases

**Manual edits detected:**

```
1. Show diff: "The PR body has been manually edited. Here's what changed:"
2. Ask: "Overwrite manual edits, merge, or cancel?"
   - Overwrite: Replace with new generated body
   - Merge: Preserve manually-added sections
   - Cancel: Keep current body
```

**No material changes in update:**

```
"Analyzed commits - no material changes to scope or impact.
The current PR description is still accurate."

Action: Skip update unless user forces
```

**Draft in progress:**

```
"Found existing draft for '<title>'.
Use existing draft, create new, or cancel?"
```

**Scratch directory doesn't exist:**

```
mkdir -p .scratch/pr-bodies/drafts
```

## Change Detection Algorithm

```bash
# 1. Quick hash check
current_hash=$(gh pr view body -q .body < number > --json | shasum -a 256)
last_hash=$(jq -r .last_generated_hash .scratch/pr-bodies/ < number > /metadata.json)

# 2. If hashes match → no changes
if [ "$current_hash" = "$last_hash" ]; then
  echo "No manual edits detected"
  exit 0
fi

# 3. If hashes differ → compute diff
gh pr view body -q .body < number > --json > /tmp/current.md
cat .scratch/pr-bodies/ < number > / < last-timestamp > -body.md > /tmp/last.md
diff -u /tmp/last.md /tmp/current.md

# 4. Analyze diff
# - Whitespace only? → Not material
# - Content changes? → Material, set manual_edits_detected = true
```

## Integration with Other Skills

**working-in-scratch-areas:**

- All drafts go to `.scratch/pr-bodies/`
- Auto-creates directory structure

**git-preferences-and-practices:**

- Respects git workflow preferences
- Works with branch naming conventions

**Repository conventions:**

- Checks for ADRs and references them
- Links to docs/plans if design doc exists

## Example Workflows

### Creating a PR

```
User: "create a PR for this branch"

Claude: "I'm using the gh-pr skill to create the pull request."
[Analyzes commits: 5 commits adding spotlight exclusion patterns]
[Checks for templates: none found]
[Generates draft in .scratch/pr-bodies/drafts/add-spotlight-patterns.md]

Claude: "Here's the draft PR. The summary focuses on the pattern-based
approach and easier maintenance. Does this look good?"

[Shows draft content]

User: "yes"

Claude: [Creates PR #123]
"Created PR #123: Add spotlight exclusion patterns
https://github.com/user/repo/pull/123"
```

### Updating After Changes

```
User: "update the PR"

Claude: "I'm using the gh-pr skill to update the pull request."
[Checks PR #123]
[Hash check: no manual edits]
[Analyzes commits: 3 new commits adding monitoring tools]

Claude: "I've added 3 commits since the PR was created. The scope has
expanded to include monitoring tools. Should I update the description?"

User: "yes"

Claude: [Generates new body]
"Here's what would change in the description:

+ ## Monitoring
+ Includes live monitoring and activity analysis tools

Look good?"

User: "yes"

Claude: [Updates PR]
"Updated PR #123 description"
```

### Adding a Comment

```
User: "comment on the PR about the changes"

Claude: "I'm using the gh-pr skill to comment on the pull request."
[Checks PR #123: has 2 review comments]

Claude: "This PR has review comments. I'll add a comment about the
recent updates. Here's the draft:

---
I've updated the PR to address the feedback:
- Added input validation for pattern file paths
- Improved error messages for invalid patterns
- Updated tests to cover edge cases

The validation now catches malformed patterns before attempting expansion.
---

Look good?"

User: "yes"

Claude: [Posts comment]
"Added comment to PR #123"
```

## File Management

**Keep:**

- metadata.json (permanent record)
- Last 5 timestamped bodies/comments
- Current draft (if in progress)

**Clean up:**

- Completed drafts after PR creation
- Old timestamped files (optional: >30 days)

## Implementation Notes

**Hash algorithm:** Use `shasum -a 256` for consistency

**Timestamp format:** ISO 8601 with hyphens for filenames: `2025-11-07T10-30-00`

**Slugification:** Lowercase, hyphens, strip special chars: "Add Spotlight Skill" → "add-spotlight-skill"

**Base branch detection:**

```bash
# Try to detect from gh pr view first
base=$(gh pr view --json baseRefName -q .baseRefName 2> /dev/null)

# Fall back to common defaults
if [ -z "$base" ]; then
  if git show-ref --verify --quiet refs/heads/main; then
    base="main"
  else
    base="master"
  fi
fi
```