Analyzes the git diff between the current branch and the default branch to generate a concise, informative PR description suitable for code review and commit history.
Core Principles
- Concise for quick reading: Facilitate rapid comprehension by a human reviewer
- Context, not repetition: Provide context to aid review, not a verbatim list of what changed
- Big picture focus: Explain why and how things changed, not every individual change
- Title separate from body: Title can be provided separately; don't duplicate it in the body
Workflow
-
Identify the remote and default branch: don't assume the remote is
origin— resolve the remote-tracking HEAD dynamically, e.g.:- Pick a remote (typically the only one returned by
git remote; otherwise prefer the upstream of the current branch viagit rev-parse --abbrev-ref --symbolic-full-name @{u}and take its remote prefix). - Resolve the default branch from that remote's HEAD:
git symbolic-ref --short refs/remotes/<remote>/HEAD(orgit rev-parse --abbrev-ref <remote>/HEAD), which yields<remote>/<default-branch>. - Fallback when no remote-tracking HEAD is configured: run
git remote set-head <remote> --auto(or ask the user) and retry; if that still fails, fall back to<remote>/main(or<remote>/master) only after confirming the branch exists withgit rev-parse --verify <remote>/<branch>. - Use the resolved
<remote>and<default-branch>consistently in the commands below.
- Pick a remote (typically the only one returned by
-
Refresh and get the diff: fetch the resolved default branch from the remote so the diff base is current, then diff against the remote-tracking ref:
git fetch --prune <remote> <default-branch>git diff <remote>/<default-branch>...HEAD
Always diff against
<remote>/<default-branch>(not the local<default-branch>) so a stale local copy can't yield a misleading PR description. -
Analyze changes to understand intent, scope, and technical decisions
-
Generate description following the structure below
Structure
[Overview paragraph]
## Changes
- **Component/Area**: Big-picture change with why/how context
- **Component/Area**: Big-picture change with why/how context
## Why
[Explanation of key technical decisions and reasoning]
Title (Optional)
- Provide separately if requested
- One-line summary of what was added/changed/fixed (the "what", not the "why")
- Omit branch name (redundant)
- Examples: "Add pgBackRest S3 credential rotation", "Implement storage guard write restrictions"
Overview
- 1-2 sentences explaining purpose and motivation
- Provide context for why this change exists
- Set the stage for understanding the changes
Changes
- Focus on big picture, not exhaustive enumeration
- Explain why and how things changed, providing context for code review
- Organize by component/service/area for multi-component changes
- Cite key files, functions, or modules when it aids understanding (use repo-relative paths only)
- Include concrete technical details when they matter: timeouts, limits, formats, protocols
- Omit tangential changes (import organization, minor refactors) unless they're the focus
- Skip "improved observability" unless it's the PR's primary purpose
Why
- Explain reasoning behind key technical decisions
- Address "why this approach over alternatives"
- Highlight security, performance, or reliability implications when relevant
- Connect decisions to constraints or requirements
Guidelines
Do:
- Keep it concise for quick reading by reviewers
- Provide context to facilitate code review, not verbatim change lists
- Focus on big-picture why/how, not exhaustive what
- Use repo-relative paths only (e.g.,
src/lib.rs, never/home/user/project/src/lib.rs) - Cite key files/functions/modules when it aids understanding
- Explain technical decisions with concrete reasoning
- Organize multi-service changes by component
Don't:
- List every change (focus on the bigger picture)
- Repeat what's visible in the code review itself
- Include branch name in description (redundant)
- Duplicate title in the body (title can be provided separately)
- Mention tangential changes like "organized imports" or "added logging" unless focal
- Use vague statements like "removed unused code" without specifics
- Treat observability as a feature (it's table stakes)
- Use absolute filesystem paths
Output Format
Provide two separate outputs:
- The title as plain text (not in a markdown block)
- The PR description body in a single Markdown code block
Format:
[One-line summary]
[PR description body without title - no nested blocks]
Critical: Do NOT nest markdown blocks. Do NOT put the title inside the same markdown block as the body. Provide them as two distinct outputs.
Example
For a change adding S3 credential rotation:
Add pgBackRest S3 credential rotation worker
Implements automatic rotation of S3 credentials for pgBackRest backups to comply with 90-day credential expiration policy.
## Changes
- **Credential management**: New background worker (`src/pgbackrest_credentials_worker.rs`) fetches fresh S3 credentials from the platform API every 24 hours and updates pgBackRest configuration. Added `prisma_postgres.s3_credentials_url` GUC setting for the API endpoint.
## Why
S3 credentials expire after 90 days. Rather than manual rotation or backup failures, the worker proactively refreshes credentials well before expiration. The 24-hour interval provides a safety margin while avoiding unnecessary API calls.