pr-builder

Imported from gsilvapt/dotfiles (skills/pr-builder/SKILL.md). Install upstream with npx skills add gsilvapt/dotfiles --skill pr-builder. Copyright stays with the author.

PR Builder

Overview

Gather comprehensive context for pull requests by collecting git history, related issues, tests, and code changes to provide a complete understanding for review or creation.

Repository Instructions

Before inspecting or describing changes, find and read the AGENTS.md and CLAUDE.md files that apply to the repository and each changed file. Search from the repository root through the changed files' directories so ignored or nested instruction files are not missed.

Treat applicable repository instructions as authoritative, including when they conflict with user-provided instructions. More specific nested instructions take precedence over parent-directory instructions. Follow their guidance for commands, testing, generated files, formatting, and PR content.

When to Use

Use this skill when:

• Creating a new pull request
• Asked to "get context on PR #123"
• Preparing to write a PR description

Creating a PR

When creating a PR, follow these steps:

1. Ensure Branch is Ready

# Make sure you're on the feature branch
git status

# Ensure branch is up to date with main
git fetch origin
git rebase origin/main  # or git merge origin/main

# Push to remote
git push -u origin username-RUN-123-feature-name

2. Gather Context for PR Description

Use the context gathering workflow in the references to understand:

• What changed and why
• Related issues/tickets
• Where the noise is -- code generators, re-renders, vendored files, mechanical renames, formatting, lockfile churn. Necessary, but not where review effort should go.
• Test coverage
• Breaking changes or migrations

Identifying the Noise

The goal is not to hide generated changes -- they still need to be present and correct -- but to point the reviewer at the source of truth instead of its output. For every generated or mechanical artifact there is a hand-written input that actually deserves review; the artifact itself only needs a skim to confirm it regenerated cleanly.

Common categories, and what to review instead of the artifact:

Two reviewer reflexes worth calling out:

• If a rendered output changed but its template did not, treat the output as suspect -- it should never drift on its own.
• Lockfile churn with no matching manifest change usually means a stale or hand-edited lockfile.

Note: build output that is git-ignored never reaches a diff, so it is not review noise -- if you see it, something is misconfigured.

3. Create the PR

Build the PR body with these rules:

• Keep Summary to at most three short bullets. Use Adds, Modifies, and Removes labels, including only the categories that apply. Describe the branch's net effect rather than its implementation journey. Omit file-by-file or commit-by-commit narration, test details, and internal planning context.
• Under Commit History, list each commit as a bare full hash, one per line, in chronological order. Underneath the hash, add the commit's contents prefixed by > so GitHub highlights it as a quote. Generate the list with git log --reverse --format='%H' main..HEAD, replacing main with the actual base branch.
• Add Breaking Changes only when the branch introduces breaking changes. Concisely state each break, who or what it affects, and the required migration or operator action.
• Add Deployment Notes only when users or operators must act before, during, or after deployment. State the required action, timing, and verification. For long-running or heavy migrations, flag the expected impact, recommend monitoring progress, and explain how to verify successful completion.
• The PR description should be short, yet concise and specific. Do not overdo it the description which will make it hard for reviewers to read.

# Create PR with gh CLI
gh pr create --title "feat(scope): brief description" --body "$(cat <<'EOF'
## Summary
- Adds: the new behavior or capability introduced by the branch.
- Modifies: the existing behavior changed by the branch.
- Removes: the behavior or capability removed by the branch.

## Review Focus

This section contains the file names, functions and line ranges that hold the real logic changes.

## Commit History

full commit hash
> pr body

another full commit hash
> pr body

## Related Issues
Fixes RUN-123
Fixes SENTRY-123
EOF
)"

PR Title Format: Follow conventional commits format:

<type>(<scope>): <description>

Examples:
feat(api): add bulk detection endpoint
fix(rrq): resolve memory leak in source poller
refactor(frontend): simplify authentication flow

Quick Reference

Context Gathering Commands

# PR overview
gh pr view 123

# Commit history
git log main..HEAD

# Full diff
git diff main...HEAD

# Changed files
git diff --name-only main...HEAD

# CI status
gh pr checks 123

# Search commits for issues
git log main..HEAD --grep="RUN-"

PR Creation Commands

# Create PR
gh pr create --title "feat: description" --body "..."

# Create draft PR
gh pr create --draft

# View created PR
gh pr view

PR Review Commands

# Checkout PR
gh pr checkout 123

# Review and approve
gh pr review 123 --approve

# Request changes
gh pr review 123 --request-changes

# Add comments
gh pr review 123 --comment

Using GitHub CLI Effectively

# List open PRs
gh pr list

# List your PRs
gh pr list --author @me

# View PR in browser
gh pr view 123 --web

# Check specific PR checks
gh pr checks 123

# Merge a PR
gh pr merge 123 --squash  # or --merge or --rebase