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:

1. Verify existence : Run git show HEAD:path/to/file to confirm
2. Link to files : Use markdown links with relative paths from repo root
   • Files: [filename.ts](path/to/filename.ts)
   • Specific lines: [filename.ts:42](path/to/filename.ts#L42)
   • Line ranges: [filename.ts:42-51](path/to/filename.ts#L42-L51)
3. Include code snippets : For configuration changes, show actual values
4. 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](path/to/file.ts)
- Configuration: [link to config](path/to/config.yaml)

**Stack Commands:**
- `./stack command_name` - Description

**Documentation:**
- [Link to relevant docs](doc/path/to/doc.md)

[Repeat structure for each major category]

## Code Impact

| Category | Added | Removed | Net |
|---|---|---|---|
| App code | X | X | X |
| Stories | X | X | X |
| Mocks | X | X | X |
| Generated | X | X | X |
| Ops/Infra | X | X | X |
| Config/Assets | X | X | X |
| **Total** | **X** | **X** | **X** |

[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](https://claude.com/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

1. Verify before documenting - Always use git show HEAD:file to confirm features exist in final state
2. Never mention removed features - If a commit added something but it was later removed or reverted, don't include it
3. Focus on outcomes, not process - Describe the result, not the development journey
4. Link to actual code - Every major feature should have a file reference that users can click
5. Be specific - "Add MySQL native password authentication" not "Update database config"
6. Test your claims - If you say "CI runs connectivity checks", verify the CI file actually shows that
7. Use present tense - "Adds X", "Implements Y", not "Added X", "Implemented Y"
8. 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](/Users/kross/project/src/config.ts)
# RIGHT: [config.ts](src/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>

Weekly Installs

0

Repository

alienfast/claude

First Seen

Jan 1, 1970

Security Audits

Gen Agent Trust HubPassSocketWarnSnykPass