Pr creation

Pull Request Creation Skill

IMPORTANT: Always follow this skill before creating any PR. Do not skip steps, especially the iterative compress-critique-fix loop.

When to Use

Activate this skill when the user says any of the following (or similar):

• “Create a PR” / “Create a pull request”
• “Open a PR” / “Open a pull request”
• “Make a PR for this”
• “Submit this for review”
• “Push and create a PR”
• “I’m done, create the PR”
• “Can you PR this?”
• “Send this up for review”
• “The feature is done” / “I’m finished” / “Ship it”

Also activate when:

• You have just finished implementing a new feature, fix, or refactor—run the loop, then create the PR
• The user asks you to submit completed work
• CLAUDE.md or task instructions say to create a PR when done

Do NOT use this skill for:

• Reviewing an existing PR (use gh pr view or gh pr diff instead)
• Merging a PR (gh pr merge)
• Updating a PR description only (just run gh pr edit)

Prerequisites

• GitHub CLI (gh) must be authenticated
• All changes must be committed to a feature branch (not $CLAUDE_CODE_BASE_REF/master)

Updating an Existing PR

Before updating an existing PR (pushing new commits, editing the description, etc.), you MUST check its current status:

1. Run gh pr view <pr-number> --json state to check the PR state
2. Based on the result:
   • Open: Proceed with the update normally
   • Merged: Do NOT update it. Create a new PR instead with the additional changes
   • Closed (not merged): Ask the user what they’d like to do, if not already clarified

Workflow

Step 1: Gather Context

1. The base branch is in the env variable $CLAUDE_CODE_BASE_REF
2. Run git diff <base-branch>...HEAD to see all changes
3. Run git log <base-branch>..HEAD --oneline to see all commits
4. Review the changed files to understand the scope
5. Check for PR description guidance—look for CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md, or similar files in the repo. If found, read them and adapt the PR description to follow the repository’s conventions (see pr-templates.md for details)
6. Deferred-item sweep—search plan/handoff docs and follow-up lists (TODO files, open sub-issues, notes in PR descriptions or linked issues) for items that touch this PR’s area:
   • Small, clearly-wanted items: fold them into this PR before opening it
   • Larger items: open follow-up PRs in the same session immediately after this one; note them in the PR description
   • Questionable items: surface in chat before proceeding
   • Update any plan/handoff doc’s status for items this PR completes or moots

Step 2: Push and Create the Pull Request

You MUST read pr-templates.md for the PR template and formatting guidelines before this step.

1. Push the branch: git push -u origin HEAD

2. Check if a PR already exists for the current branch:

   EXISTING_PR=$(gh pr list --head "$(git branch --show-current)" --json number --jq '.[0].number' 2>/dev/null)
   

   If a PR already exists, update it with gh pr edit instead of creating a new one.

3. Create the PR using gh pr create with the template from the resource file. Make sure that you use the target branch

Write the body for the reviewer's cognitive budget, not as an investigation archive — see pr-templates.md "Body Guidelines" for the evidence and the rules. The load-bearing ones: lead with what the PR does (inverted pyramid — root-cause forensics go below the fold, never above the statement of the change); make length proportional to the reviewable diff (a ~10-line change is a few sentences, not a 500-word skeleton); omit empty ritual sections instead of spending a paragraph to say "None"; and add a Review focus line naming the file to read first, the cross-file invariant, and the part you're least sure of — the single element most correlated with a human actually engaging, which matters because agent-authored PRs are systematically under-reviewed. Describe the diff as it currently stands, never its own history (pr-templates.md carries the rule). Use the exact headings from pr-templates.md (What & why / Review focus / How it was tested / Decisions made / Lessons Learned) so a reviewer can scan by habit.

Step 3: Iterative Compress-Critique-Fix Loop

CI is already running; use this time to improve the code.

Run an iterative loop until you reach a fixed point—a full critique pass that turns up nothing worth changing. This is the same loop described in CLAUDE.md’s Self-Critique Loop section; apply it here on the full diff.

You MUST read .claude/skills/pr-creation/critique-prompt.md once before the first pass—it contains the detailed checklist the sub-agent needs.

Each pass:

1. Launch a critique sub-agent using the Task tool:
   • subagent_type: “general-purpose”
   • description: “Critique code changes”
   • prompt: Include the full diff (git diff $CLAUDE_CODE_BASE_REF...HEAD) and the critique prompt from the resource file
2. For each issue raised, assess validity, then take the easy wins first:
   • Compress—delete dead code, unused imports, commented-out blocks, WHAT-comments, backwards-compat shims, premature abstractions
   • Readability—tighter names, un-nest conditionals, combine related checks, guard-clause early returns
   • Code reuse—extract duplicated logic into helpers; search for existing utilities before adding new ones
   • Parametrize tests—collapse near-identical tests into a single parametrized/table-driven test with exact-equality assertions
   • Fixtures—pull repeated setup/teardown into shared fixtures
   • Correctness—bugs, edge cases, security, swallowed errors
3. Commit the fixes (Conventional Commits format, per CLAUDE.md)
4. Start a fresh critique pass—the previous output is now stale

Stop when a full pass returns no actionable issues. Cap at ~5 passes; if issues are still being found at pass 5, stop, summarize what’s left, and ask the user how to proceed rather than looping silently.

Skip the loop for trivial changes (typo fixes, single-line config tweaks, pure docs edits)—say so explicitly when you skip.

Step 4: Run Validation

Run the project’s test/lint/typecheck commands (see pr-templates.md for common commands per language). Fix any failures before proceeding. If validation surfaces new defects, loop back into Step 3 with the fixes included.

Step 5: Update PR Title and Description (after any post-creation changes)

Push any commits made during the critique and validation steps, then update the PR to reflect the final state.

1. Push: git push

2. Re-read the diff (git diff $CLAUDE_CODE_BASE_REF...HEAD) and commit log (git log $CLAUDE_CODE_BASE_REF..HEAD --oneline) to see the full scope

3. Rewrite the title and body to accurately describe the current totality of changes, not just the original scope:

   gh pr edit <pr-number> --title "<type>: <updated description>" --body "$(cat <<'EOF'
   <updated body using template from pr-templates.md>
   EOF
   )"
   

Skip the description update if no commits were made after Step 2.

Step 6: Wait for CI Checks (MANDATORY)

1. Run gh pr checks <pr-number> --watch to monitor
2. If any checks fail, investigate and fix the issues
3. Push fixes, update the PR description (Step 5), and wait again
4. Only proceed once all checks are green

Step 7: Scrub AI Attribution from the Description

Re-read the current PR description (gh pr view <pr-number> --json body --jq .body) and remove anything related to “authored by Claude Code” or similar AI-tool attribution—claude.ai URLs, session links, “Generated with Claude Code” footers, co-author lines referencing Claude, etc. This mirrors the CLAUDE.md rule to never include such links in PRs, and catches any that slipped in via templates or earlier edits. If any are found, update the description with gh pr edit to remove them.

Step 8: Report Result

Provide the PR URL and confirm all CI checks have passed.

Step 9: Iteration Retrospective

After reporting the result, briefly reflect on how you could have iterated faster on this task. Consider:

• Parallelization: Which investigations, tool calls, or sub-agent launches could have run in parallel instead of sequentially?
• Targeted checks over full sweeps: Were there broad searches or full test runs you ran locally that CI would have caught anyway? Could a more targeted check (single file, single test, quick lint) have been faster?
• Earlier CI delegation: CI started at Step 2; did the critique loop or local validation catch issues CI would have caught anyway?
• Critique loop efficiency: Did any critique passes surface issues that a quick re-read would have caught before launching the sub-agent?

State each insight as one concrete line. Skip this step if the task was trivial (single-file, no iteration needed).

Examples

Example 1: Simple Bug Fix

User says: “I’m done fixing the login bug, create a PR”

Claude’s actions:

1. Runs git diff $CLAUDE_CODE_BASE_REF...HEAD—sees changes in src/auth/login.ts and tests/auth/login.test.ts
2. Runs git log $CLAUDE_CODE_BASE_REF..HEAD --oneline—sees 2 commits
3. Pushes and creates PR: gh pr create --title "fix: handle null session token in login flow" --body "..."—CI starts immediately
4. Launches critique sub-agent with the diff
5. Critique returns: “Looks good, minor suggestion to add null check on line 42”
6. Fixes the null check, commits: fix: add null check for empty session token
7. Runs pnpm check && pnpm test && pnpm lint—all pass
8. Pushes fixes, updates PR description to reflect the null-check fix
9. Watches CI with gh pr checks 47 --watch—all green
10. Reports: “PR #47 created and all CI checks pass: https://github.com/org/repo/pull/47"

Example 2: Multi-Commit Feature

User says: “Submit this for review”

Claude’s actions:

1. Runs git diff $CLAUDE_CODE_BASE_REF...HEAD—sees changes across 8 files including new components, tests, and API routes
2. Runs git log $CLAUDE_CODE_BASE_REF..HEAD --oneline—sees 5 commits
3. Pushes and creates PR with a draft description—CI starts immediately
4. Pass 1: Critique flags 4 issues—unused import, two near-identical tests that should parametrize, duplicated validation logic across 2 components, an over-engineered single-caller wrapper. Fixes them: deletes the import, collapses the tests with it.each, extracts a shared validateInput helper for the duplication, inlines the single-caller wrapper. Commits.
5. Pass 2: Critique flags 2 more—a leftover WHAT-comment from the refactor and a nested conditional. Un-nests and removes the comment. Commits.
6. Pass 3: Critique returns clean—fixed point reached, exit loop.
7. Runs validation—all pass
8. Pushes fixes, updates PR title and description to reflect all changes
9. Watches CI—one check fails (lint warning on new file)
10. Fixes lint issue, pushes, updates PR description again—all green
11. Reports success with PR URL

Example 3: Ambiguous Follow-up

User says: “Push this up”

Claude’s actions: Pushes the branch and opens a PR against $CLAUDE_CODE_BASE_REF by default — finishing work is the explicit ask per CLAUDE.md. Only pushes without opening a PR if the user said not to, or a PR for this branch already exists (then updates that PR instead).

Error Handling

• Critique finds issues: Fix them before proceeding—do not skip
• Tests fail: Fix the tests, don’t skip them
• gh not authenticated: Tell user to run gh auth login or set GH_TOKEN
• Push fails: Check branch permissions and remote configuration
• PR already exists (HTTP 422): Check for existing PRs first with gh pr list --head "$(git branch --show-current)", then use gh pr edit to update
• No changes to PR: Confirm with the user that work is committed

Shaping the PR

Default to ONE consolidated PR even when a task produces several independent changes. Every PR boots the full workflow fan-out on a shared runner pool, so N small PRs cost ~N× the CI and each one's required checks queue behind the others' long jobs. Land related and merely co-discovered work on one branch, one CI run, one review. Split only when a piece must land on its own timeline, or the consolidated diff would be too large to review coherently. One big PR still owes the reviewer legibility: one commit per separable concern, plus a ## Partitions map in the body.

Use the /pr-creation skill. For contributions to others' repos, before writing a PR description, check for CONTRIBUTING.md or .github/PULL_REQUEST_TEMPLATE.md in the target repo and follow its conventions. Never include claude.ai URLs, session links, or AI-tool attribution links in PRs.

A ## Lessons Learned section is the exception, not the norm — most PRs should have none. Each PR that carries one files an issue on the template repo (phone-home propagates it on merge), so the bar is high: include one only for a genuinely novel, non-obvious insight that generalizes to a downstream repo sharing none of this code and would change a template file (.claude/, .hooks/, .github/workflows/, CLAUDE.md, setup.sh). A repo-specific fix, a restatement of an existing rule, or an obvious CI tweak is triage noise — omit the section. When you do include one, each lesson must be actionable: what to change in the template, where (file/component), and why. Never write a negative placeholder ("none applicable", "N/A", "nothing generalizable") — phone-home drops those, so the sentence only churns; delete the heading entirely.

Skip the ## Lessons Learned section entirely when the PR targets the claude-automation-template repo itself. phone-home propagates lessons from downstream repos into the template; a change made directly in the template is already there, so a lessons section here propagates nothing and is pure noise.

Lessons only reach the template repo if they appear in the PR description—lessons mentioned only in chat are never propagated and are permanently lost.

Resolve each review thread once you've addressed it, so the unresolved count reflects only what still needs attention and auto-merge isn't held on stale threads. Resolve only a thread you actually addressed — a fix or a reply first, never resolving to clear the count.

No automated resolver covers it — every thread is resolved by whoever addressed it. Review findings resolved reads a gating (🔴/🟡) thread's resolved flag, not the diff, so one addressed-but-unresolved finding blocks the merge indefinitely. Resolving also fires no workflow event, so re-run the gate right after: gh pr edit <N> --remove-label recheck-review-gate then --add-label recheck-review-gate. Both halves, in that order — a bare add over a label already present fires nothing, since labeled fires on a transition. See CLAUDE.md's Pull Requests section for the mechanism.