pull-request

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