PR Title and Description Generator

Generate or update a PR title and description based on the actual changes in the current branch.

Core Principle

Document ONLY what exists in the final state of the code, not the development history.

Bash Command Rule

NEVER prefix bash commands with comment lines. Permission patterns in ~/.claude/settings.json match against the start of the command. A leading # comment breaks the match and triggers a manual permission check. Put descriptions in the Bash tool's description parameter instead.

If a feature was added in one commit and removed in another, it should NOT be in the PR description. Always verify features exist in HEAD before documenting them.

Analysis Process

1. Identify Current Branch and PR

git branch --show-current

Fetch PR information including state for validation

pr_info=$(gh pr view --json number,title,state,mergedAt,headRefName,baseRefName 2>/dev/null)

if [[ -n "$pr_info" ]]; then

PR exists - extract state and metadata for validation

pr_state=$(echo "$pr_info" | jq -r '.state // "UNKNOWN"') pr_merged_at=$(echo "$pr_info" | jq -r '.mergedAt // "null"') pr_number=$(echo "$pr_info" | jq -r '.number') pr_title=$(echo "$pr_info" | jq -r '.title') pr_head=$(echo "$pr_info" | jq -r '.headRefName') pr_base=$(echo "$pr_info" | jq -r '.baseRefName')

Security Fix #4: Validate pr_state is a known GitHub PR state (prevent injection)

case "$pr_state" in OPEN|CLOSED|MERGED|UNKNOWN) # Valid state, proceed ;; *) echo "WARNING: Unexpected PR state from GitHub API: $pr_state" >&2 pr_state="UNKNOWN" ;; esac

Security Fix #4: Validate pr_merged_at is either "null" or valid ISO 8601 timestamp

if [[ "$pr_merged_at" != "null" ]] && [[ ! "$pr_merged_at" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T ]]; then echo "WARNING: Unexpected mergedAt format from GitHub API: $pr_merged_at" >&2 pr_merged_at="null" fi

Security Fix #5: Validate pr_number is present and is a positive integer

if [[ -z "$pr_number" ]] || [[ ! "$pr_number" =~ ^[0-9]+$ ]]; then if [[ -n "$pr_info" ]]; then echo "ERROR: PR data incomplete (missing or invalid PR number)" >&2 fi pr_info="" # Treat as no PR exists fi fi

1.1. PR State Validation

CRITICAL SAFEGUARD: Before updating any PR, verify it is in a safe state to modify.

When PR exists (pr_info is not empty):

Step 1: Check if PR is OPEN - safe to proceed immediately:

if [[ "$pr_state" == "OPEN" ]]; then

Safe to proceed with normal update workflow

Continue to Step 2

fi

Step 2: If PR is NOT OPEN - stop and ask user for confirmation:

Determine the specific non-open state:

if [[ "$pr_state" == "MERGED" || "$pr_merged_at" != "null" ]]; then pr_status_type="MERGED" pr_status_detail="merged" pr_status_note="Note: Updating a merged PR only changes its historical record, not the code." elif [[ "$pr_state" == "CLOSED" ]]; then pr_status_type="CLOSED" pr_status_detail="closed without merging" pr_status_note="Updating a closed PR is unusual. Most cases should create a new PR instead." else pr_status_type="UNKNOWN" pr_status_detail="in an unclear state ($pr_state)" pr_status_note="Cannot verify PR state safely. Manual investigation recommended." fi

Step 3: Present confirmation prompt to user:

Stop execution and display this message (substitute variables with actual values):

⚠️ PR State Warning

The detected pull request is {pr_status_type}:

• PR: #{pr_number} - {pr_title}
• Branch: {pr_head} → {pr_base}
• State: {pr_status_detail}

Options:

1. Create new PR - Open a fresh pull request for these changes (recommended for most cases)
2. Update {pr_status_type} PR anyway - Modify the PR's title/description (rarely needed)
3. Cancel - Stop without making changes

{pr_status_note}

What would you like to do?

Step 4: Wait for explicit user response and validate input:

Read user choice

read -p "Enter your choice (1, 2, or 3): " user_choice

Security Fix #2: Validate input is exactly 1, 2, or 3

if [[ ! "$user_choice" =~ ^[123]$ ]]; then echo "Invalid choice. Please enter 1, 2, or 3." >&2 exit 1 fi

Step 5: Handle user choice based on validated input:

case "$user_choice" in 1) # Option 1: Create new PR pr_info="" echo "Creating new PR instead..." ;; 2) # Option 2: Update anyway user_confirmed_update="true" echo "Proceeding with update to $pr_status_type PR..." ;; 3) # Option 3: Cancel user_cancelled="true" echo "PR update cancelled by user. No changes made." exit 0 ;; esac

Note on Interactive vs Non-Interactive Handling:

If implementing this skill as a non-interactive script, Claude should directly handle the user's verbal choice without prompting:

• If user says "create new PR": Set pr_info=""

• If user says "update anyway": Set user_confirmed_update="true"

• If user says "cancel": Exit gracefully

When no PR exists (pr_info is empty): Skip validation entirely - the skill will create a new PR (normal workflow).

API Failure Handling: If gh pr view returns an error OTHER than "no pull requests found", treat as UNKNOWN state and ask user before proceeding.

2. Analyze Final State Changes

Get commit count:

git log main..HEAD --oneline | wc -l

Get file change summary:

git diff main...HEAD --stat

Identify major areas of change:

git diff main...HEAD --name-only | cut -d/ -f1 | sort | uniq -c | sort -rn

3. Code Impact Summary

Generate a categorized line-count breakdown to quantify the PR's impact. This section helps reviewers quickly understand the scope and nature of changes.

Step 1: Get the raw totals (with rename detection):

git diff --shortstat -M main...HEAD

Step 2: Categorize by purpose using git diff --numstat :

git diff --numstat -M main...HEAD | awk '{if ($3 ~ /lock.yaml$|lock.json$|.lock$/) next; added+=$1; removed+=$2; file=$3; if (file ~ /.stories./) {sa+=$1; sr+=$2} else if (file ~ /mock|Mock/) {ma+=$1; mr+=$2} else if (file ~ /generated|packages/graphql//) {ga+=$1; gr+=$2} else if (file ~ /ops//) {oa+=$1; or+=$2} else if (file ~ /.(yml|yaml|json|css|scss|svg|md)$/) {la+=$1; lr+=$2} else {ca+=$1; cr+=$2}} END {printf "%-20s %8s %8s %8s\n", "Category", "Added", "Removed", "Net"; printf "%-20s %8d %8d %8d\n", "App code", ca, cr, ca-cr; printf "%-20s %8d %8d %8d\n", "Stories", sa, sr, sa-sr; printf "%-20s %8d %8d %8d\n", "Mocks", ma, mr, ma-mr; printf "%-20s %8d %8d %8d\n", "Generated", ga, gr, ga-gr; printf "%-20s %8d %8d %8d\n", "Ops/Infra", oa, or, oa-or; printf "%-20s %8d %8d %8d\n", "Config/Assets", la, lr, la-lr; printf "%-20s %8d %8d %8d\n", "TOTAL", added, removed, added-removed}'

Notes:

• Use -M flag for rename detection (prevents inflated counts from file renames)

• "App code" captures source code files (ts, tsx, rb, etc.) — config/asset files (yml, json, css, lock, svg, md) are separated into "Config/Assets" to keep the signal clean

• Adjust category patterns to match project structure:

• .stories. — Storybook story files

• mock|Mock — Test mocks

• generated|packages/graphql/ — Generated code (GraphQL codegen, etc.)

• ops/ — Infrastructure/operations

• lock.yaml$|lock.json$|.lock$ — Lock files (skipped entirely)

• .(yml|yaml|json|css|scss|svg|md)$ — Config, locales, styles, assets

• The categorized breakdown often reveals a different story than raw totals (e.g., production code reduced while test coverage increased)

• If cloc is available, cloc --diff main HEAD --git provides an alternative per-language breakdown, but lacks categorization and doesn't handle renames

Include the resulting table in the PR description under a Code Impact section.

4. Verify What's Actually in the Code

CRITICAL: For each area of apparent change, verify if it's in the final state:

Check if a feature is in final code:

git show HEAD:path/to/file.ts | grep -q "feature_name" && echo "PRESENT" || echo "REMOVED"

Example — check for authentication plugin:

git show HEAD:cloud/database/src/SqlDatabase.ts | grep "authentication_plugin"

Example — check if a function exists:

git show HEAD:src/utils.ts | grep -A10 "function myFunction"

If a feature doesn't appear in the final state, DO NOT include it in the PR description.

5. Categorize Changes by Impact

Organize changes into categories based on what's actually present:

• Infrastructure Changes: Cloud resources, deployments, architecture

• Developer Experience: Tooling, documentation, local development setup

• CI/CD: Pipeline changes, automation workflows

• Breaking Changes: API changes, configuration requirements, migration needs

• Dependencies: Package updates that remain in final package.json/lock files

• Documentation: New or updated docs (verify files exist)

6. Document Only Present Changes

For each change area:

• Verify existence: Run git show HEAD:path/to/file to confirm

• Link to files: Use markdown links with relative paths from repo root

• Files: filename.ts

• Specific lines: filename.ts:42

• Line ranges: filename.ts:42-51

• Include code snippets: For configuration changes, show actual values

• Provide context: Explain why the change was made, not just what changed

Quality Verification Checklist

Before finalizing the description, verify:

• Every feature mentioned exists in git show HEAD:path/to/file

• No references to features that were added then removed during development

• All file links use relative paths from repo root (not absolute paths)

• Configuration examples reflect actual current state in HEAD

• Breaking changes are clearly marked with "Breaking Changes" section

• Testing sections describe actual tests that currently pass

• Code snippets are from actual files in HEAD, not from memory

PR Title Formats

See resources/title-patterns.md for comprehensive title format examples and patterns.

Quick reference:

• Infrastructure: "Enterprise [resource] with [key feature] and [secondary feature]"

• Features: "Add [feature] with [benefit]"

• Bug Fixes: "Fix [specific issue] in [area]"

• Refactoring: "Refactor [area] to [improvement]"

Avoid vague titles like "PR deployment", "Various fixes", or "Update code".

Description Structure

For detailed templates, see:

• templates/feature.md - Feature additions

• templates/bugfix.md - Bug fixes

• templates/infrastructure.md - Infrastructure changes

Use this general template structure:

Summary

[1-2 sentence overview of what this PR accomplishes and why]

[Major Category 1 - e.g., Infrastructure Changes]

[Subcategory - e.g., Cloud SQL Enterprise Plus]

[Feature Name]:

• [Implementation detail verified in HEAD]
• [Configuration detail with actual values]
• [Benefit or impact]

Implementation:

• File: link to main file
• Configuration: link to config

Stack Commands:

• ./stack command_name - Description

Documentation:

• Link to relevant docs

[Repeat structure for each major category]

Code Impact

[1-2 sentence interpretation of what the numbers mean — e.g., "Production code reduced by X lines through Y. Net increase driven by new test coverage."]

Breaking Changes

[Area Affected]

• What changed: [Specific change]
• Migration: [Steps to migrate]
• Impact: [Who/what is affected]

Dependencies

• Updated package-name to version X.Y.Z
• Added new-package for [specific purpose]
• Removed old-package (no longer needed)

Testing

[Test Category]:

• ✅ [Specific test that validates the change]
• ✅ [Another specific test]
• ✅ [Integration test description]

[Another Test Category]:

• ✅ [Test description]

Cost Impact

[If applicable - infrastructure cost changes]

Production:

• Current: $X/month
• Planned: $Y/month (with optimization Z)
• Benefit: [SLA/performance/reliability improvements]

[Environment]:

• Base: $X/month (shared infrastructure)
• Per-[unit]: +$Y/month

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

Verification Workflow

For step-by-step examples of how to analyze and verify PR changes, see resources/analysis-workflow.md.

You can also use the verification script:

Check if a feature exists in final state:

./scripts/verify-feature.sh path/to/file.ts "feature_name"

Check if a file exists:

./scripts/verify-feature.sh packages/api/README.md ""

Important Rules

• Verify before documenting - Always use git show HEAD:file to confirm features exist in final state

• Never mention removed features - If a commit added something but it was later removed or reverted, don't include it

• Focus on outcomes, not process - Describe the result, not the development journey

• Link to actual code - Every major feature should have a file reference that users can click

• Be specific - "Add MySQL native password authentication" not "Update database config"

• Test your claims - If you say "CI runs connectivity checks", verify the CI file actually shows that

• Use present tense - "Adds X", "Implements Y", not "Added X", "Implemented Y"

• Quantify when possible - "3x performance improvement", "99.99% SLA", "$460/month cost"

Common Mistakes to Avoid

❌ Documenting Removed Features

Commit history shows:

- Commit A: Add feature X

- Commit B: Remove feature X

Final state: No feature X

WRONG: "Added feature X"

RIGHT: Don't mention feature X at all

❌ Vague Descriptions

WRONG: "Updated database configuration"

RIGHT: "Set default_authentication_plugin to mysql_native_password for Cloud SQL Proxy v2 compatibility"

❌ Missing Verification

WRONG: Assume a feature exists because you saw it in commit messages

RIGHT: git show HEAD:path/to/file.ts | grep "feature_name"

❌ Broken Links

WRONG: config.ts

RIGHT: config.ts

After Generating Description

Security Fix #1 - Command Injection Prevention: When generating title and description variables, ensure they are assigned using proper quoting to prevent command injection:

Safe assignment (use quotes):

title="Generated title text" description="$(cat <<'EOF' Multi-line description EOF )"

UNSAFE — never do this: title=$(some_command) without quotes could execute commands in the title.

Update the PR using GitHub CLI.

Pre-Update State Verification (prevent TOCTOU race condition) — re-check PR state immediately before update:

if [[ -n "$pr_number" ]]; then current_pr_info=$(gh pr view "$pr_number" --json state 2>/dev/null)

if [[ -n "$current_pr_info" ]]; then current_state=$(echo "$current_pr_info" | jq -r '.state // "UNKNOWN"')

# Verify state hasn't changed since initial check
if [[ "$current_state" != "$pr_state" ]]; then
  echo "ERROR: PR state changed during processing" >&2
  echo "  Initial state: $pr_state" >&2
  echo "  Current state: $current_state" >&2
  echo "  Aborting update to prevent unintended modification" >&2
  exit 1
fi

else echo "ERROR: PR no longer exists (may have been deleted)" >&2 exit 1 fi fi

if [[ "$user_cancelled" == "true" ]]; then echo "ERROR: Attempted to continue after user cancellation" >&2 exit 1 fi

if [[ "$pr_state" != "OPEN" ]] && [[ "$user_confirmed_update" != "true" ]]; then echo "ERROR: Attempted to update non-open PR #$pr_number (state: $pr_state) without user confirmation." echo "This indicates a bug in the PR state validation logic." exit 1 fi

gh pr edit <number> --title "Your Title Here" --body "$(cat <<'EOF' [Your full description here] EOF )"

Confirm the update was successful:

gh pr view <number>