Pr Merge Commit

Generate Merge Commit Message

Create a gold-standard merge commit message for the current branch. Merge commits are the user-facing, product-level summary that appears in git log --merges on the main branch.

Merge commit text is user-facing. Apply the Published-Release Test before adding rename history, ### Fixes for behavior that never shipped, or "no longer X" framing. See AGENTS.md § The Published-Release Test.

User hint: $ARGUMENTS

Context

Current branch — run this command and read the output:

git branch --show-current

Base branch detection — run this command and read the output:

git rev-parse --verify origin/main >/dev/null 2>&1 && echo main || echo master

Commits on this branch — run this command and read the output:

BASE=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo main || echo master); git log "origin/$BASE..HEAD" --oneline 2>/dev/null || echo "(no commits ahead of base)"

Files changed (stat) — run this command and read the output:

BASE=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo main || echo master); git diff "origin/$BASE...HEAD" --stat 2>/dev/null || echo "(no diff)"

Full diff — run this command and read the output:

BASE=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo main || echo master); git diff "origin/$BASE...HEAD" 2>/dev/null || echo "(no diff)"

Procedure

1. Analyze Changes

• Review the full diff and all commits on the branch — not just the latest
• Determine the nature: feature, bug fix, refactor, version bump, CI/infra, docs, breaking change, Python/runtime version drop, etc.
• Assess scope: is this a small targeted fix or a large multi-module change?
• Note any PR number visible in branch name or commits (e.g., feature-name with PR #42)
• Whole-branch perspective: describe the net shipped result — collapse fixup commits, reverts-then-re-adds, and WIP states. The merge commit is a product summary, not a commit diary.

2. Read Project Conventions

• Read AGENTS.md and/or CLAUDE.md for any merge commit or commit message format preferences
• If the project uses a scope format (e.g., scope(type[detail])), match it in the title

3. Draft Merge Commit Message

Title Line

• Under 70 characters
• Ends with (#N) if the PR number is known
• Match the project's commit scope format if one exists
• Descriptive of the impact — what changed for the user, not implementation details

Body — Proportional to the Change

Line wrapping

Wrap commit message body lines at 72 characters. This is the git convention and ensures readable output in git log, terminals, and email-based review.

Overflow exceptions — do NOT break these tokens across lines; place them at the end of a line or on their own line:

• URLs
• commit hashes
• stack traces
• file paths
• long identifiers (class names, function signatures)

If a bullet point exceeds 72 characters due to an overflow token, let the line run long rather than wrapping mid-token.

Small changes (1-3 file fix, simple bump): title line only, no body needed.

Medium changes (feature, targeted refactor, bug fix with root cause):

Opening narrative paragraph (2-4 sentences) explaining what changed and why, followed by bullet points for specific changes with bold labels.

Large changes (multi-module feature, major refactor, migration):

Full structured body with relevant sections from the patterns below.

Body Patterns — Use Only What Applies

For features, refactors, and bug fixes:

• Opening narrative paragraph: what and why (2-4 sentences)
• Bullet points with bold labels for specific changes
• Breaking changes: section if applicable, with migration guidance
• Cross-references: Fixes #N, See also:, companion PR links
• Version compatibility notes if applicable (environment tables, test matrices)

For bug fixes with non-obvious root cause:

• Narrative root-cause explanation
• Numbered reproduction steps if helpful
• Environment/version tables when the bug is version-specific

For API refactors with migration paths:

• Old/new tables showing renamed methods, parameters, or modules
• Deprecation notices with timeline
• Breaking changes: section

For version bumps:

• Arrow notation: v1.2.3 -> v1.3.0 or v1.2.3 → v1.3.0
• Release tag URL and changelog URL per package
• Release date if known
• Per-file scope annotations when multiple files change different dependencies

For Python/runtime version drops:

• EOL date
• Links to PEP and devguide references

For build/infra migrations:

• Before/after tooling description
• Summary of what changed and why the migration was needed

For multi-module sync results:

• Companion PR links
• Design decisions and trade-offs
• Test coverage summary (qualitative, not counts)

What NOT to Include

• Test counts or passing numbers ("875 tests pass")
• Git SHAs or commit hashes
• File-level line numbers
• Number of files changed
• Details the reviewer can see in the diff
• Redundant context already visible in git log

4. Present the Message

• Show the complete merge commit message in a single fenced code block
• Do NOT run any git commands — the message is for the user to copy/paste into their merge workflow (GitHub merge button, git merge --edit, squash-and-merge dialog, etc.)
• If the PR number is unknown, note where (#N) should be inserted

Rules

• Never run git merge, git commit, or any write operation — output only
• Never force-push or run destructive git commands
• Proportional: a 1-line fix = subject line only; a large feature = structured body
• Product-level focus: describe what changed for the user, not file-level diffs
• Language-agnostic: discover conventions from AGENTS.md/CLAUDE.md — never hardcode specific tool commands
• Arrow notation for version bumps: old -> new
• No brittle details: no test counts, no SHAs, no line numbers, no file-changed counts

Portability notes

• $ARGUMENTS — the text the user passed when invoking this skill. If your host does not substitute it, read it as the user's request in the current turn, and ask when there is none.