PR Description Template

Guide agents and humans to write merge requests reviewers can scan: motivation and scope, implementation summary, risk and rollback, reproducible tests, and “what I want you to focus on”—always separate what changed from why.

A strong PR body lowers first-round review cost: readers decide in one screen whether it is their review, where risk lives, and how to verify, before diving into the diff. When an agent drafts the text, default to ticket and design-doc links, and distinguish user-visible changes from internal-only refactors.

For UI changes, note screenshot or screen-recording paths; for refactors only, stress behavior parity and which test types already cover it. For large changes, add file-level navigation or commit-split notes so reviewers are not left to infer everything from the diff alone.

Why structured descriptions help

Unstructured bodies often bury motivation mid-page, paste non-reproducible test steps, or omit risk and rollback. The value of a template is not length—it is a fixed scan order so review and CI triage both move faster.

Lead with one or two sentences on the problem and who benefits, then expand into implementation.
Explicitly list what this PR intentionally does not do to reduce scope-creep debates.
Call out SRE, DBA, or security pre-approvals in the body or checklist so verbal agreements do not slip.

One-line summary: Use a full sentence for the platform title or first line of the body (for example, “Fix OAuth refresh race under concurrent use”), not a ticket-number-only placeholder.

PR lifecycle (draft to production)

Match the narrative to the phase: drafts emphasize motivation and trade-offs; during review, fold in discussion conclusions; before and after merge, add deploy order, monitoring, and rollback. The diagram below is a simplified, platform-agnostic flow—replace tool and gate names in your team SKILL.

  [ Local dev / small commits ]
            │
            ▼
      [ Open PR: title + structured body ]
            │
            ▼
  ┌─────────────────────────────┐
  │ Automation: lint / test / build │
  └─────────────────────────────┘
            │
       ┌────┴────┐
       ▼         ▼
   [ CI red ]   [ CI green ]
       │         │
       ▼         ▼
  Fix code / update body   [ Human review + discussion ]
       │                 │
       └────────┬────────┘
                ▼
         [ Approve + branch protection satisfied ]
                │
                ▼
           [ Merge to mainline ]
                │
                ▼
    [ Deploy / feature flags / monitor ]
                │
         ┌──────┴──────┐
         ▼             ▼
    [ Healthy ]   [ Rollback / hotfix ]
         │             │
         └──────┬──────┘
                ▼
            [ Close ticket / postmortem ]

Large PRs: If the diff exceeds your team threshold, explain why it cannot be split, or note “split across #xxx / #yyy”, and point to key commits or file lists—otherwise review tends to become superficial.

Recommended sections and bullets

Rename headings to match repo convention, but keep the intent. Agent output should use lists and short paragraphs, not long prose walls.

Background / goals: Link issues, RFCs, or incident write-ups; state success criteria.
Implementation highlights: Key algorithms, API changes, migration steps; call out public contract changes explicitly.
Risk and rollback: Feature flag names, DB forward/backward compatibility, canary dependencies.
Testing: Unit / integration / manual, each on its own line; prefer copy-pastable commands or script paths.
After merge: Deploy order, dashboards to watch, alert silencing windows (if any).

<!-- .github/pull_request_template.md -->
## Background / Goals
<!-- Why this change? Link to issue, RFC, or ticket -->
Closes #___

## Change Type
- [ ] Feature
- [ ] Bug fix
- [ ] Hotfix (production issue)
- [ ] Refactor / cleanup
- [ ] Docs / chore

## Implementation Highlights
<!-- Key decisions, non-obvious design choices, architecture changes -->
-

## Risk & Rollback
- **Risk level**: Low / Medium / High
- **Rollback**: <!-- how to revert if issues arise -->
- **Feature flag**: <!-- flag name if behind a flag -->

## Testing
- [ ] Unit tests added / updated
- [ ] Integration tests added / updated
- [ ] Manual testing completed (describe steps)
- [ ] Tested on staging

## After Merge
- [ ] Deploy to production (or auto-deployed?)
- [ ] Monitor error rate and P99 for 30 min
- [ ] Notify stakeholders / update docs

## Review Focus
<!-- Direct reviewer attention: "focus on X", "skip generated Y", "open question about Z" -->

From the reviewer: what to surface

Proactively list a review focus—for example, “Please scrutinize authorization checks and cache invalidation”—instead of making reviewers guess. If known tech debt remains, say whether this PR pays it down or deliberately defers it with a follow-up ticket.

Security: input boundaries, auth paths, sensitive log redaction.
Performance: hot paths, N+1, large table scans or batch sizes.
Maintainability: new dependencies, config naming aligned with existing conventions.

Working with agents

The SKILL should require the model, before drafting PR text, to read: target branch rules, team test commands, squash policy, and paths that trigger CODEOWNERS. After generation, humans mainly tune “business context” and “release window” details.

Example constraints: do not invent issue links; if the diff has no test changes, the body must say “covered by existing tests” or “why new tests are unnecessary”; for UI without screenshots, label “TODO: add screenshot” instead of omitting silently.

# PR description requirements by type

## Feature PR
- Background: link to product spec or RFC
- Scope: what is and is NOT included in this PR
- Architecture: diagram or description if multiple services affected
- Flag: feature flag name if behind a toggle (default OFF)
- Metrics: what to monitor post-deploy (conversion, error rate)

## Bug Fix PR
- Root cause: one-paragraph explanation
- Reproduction steps: how to reproduce the original bug
- Fix: what was changed and why it resolves the issue
- Tests: regression test added to prevent recurrence

## Hotfix PR
- Impact: severity, affected users/percentage, dollar impact if known
- Timeline: when issue started, when detected, when fix deployed
- Root cause: brief (full post-mortem after stabilization)
- Immediate fix: what this PR does
- Follow-up: what permanent fix or monitoring improvement is planned

## Refactor PR
- Motivation: what pain point this removes (e.g. test time, error rate)
- Scope: files/modules touched; confirm no behavior change
- Validation: how you verified behavior is unchanged (tests, comparison)
- Risk: any edge cases that could have changed behavior

Pre-merge checklist and section builder

Checkbox state is stored in this browser (localStorage, key vvskill-pr-desc-checklist-v1); section text and generated output use vvskill-pr-desc-section-builder-v1. Nothing is uploaded to a server.

Pre-merge self-check

Title or first paragraph stands alone: what changed and why it should merge
Linked ticket / design doc / related PRs (when applicable)
Test steps are reproducible (commands or paths), or you explained why not
Risk, rollback, or feature flags are clear; required pre-approvers are @mentioned
Called out files or decisions you want reviewers to focus on

Section bullets → Markdown

One bullet per line in each box, or separate with blank lines; output uses level-2 headings and unordered lists, ready to paste into a PR.

Background / goals Implementation highlights Testing and verification

SKILL outline (YAML)

Keep field names aligned with your team template when agents cite this; for monorepos or multi-service repos, add an “impact scope” section.

---
name: pr-description
description: Structured PR body, type-specific requirements, and review-ready checklist
version: 2.0
---
# PR lifecycle
- Draft: work in progress, mark [WIP] in title
- Ready for review: all checklist items complete, CI passing
- Merge: squash or rebase; ensure title follows Conventional Commits
- Deploy: confirm deployment and monitor observation window

# Required sections
- Background/Goals: link to issue, ticket, or RFC
- Implementation highlights: key decisions, non-obvious design choices
- Risk & Rollback: risk level, rollback steps, feature flag if applicable
- Testing: unit + integration + manual steps + staging validation
- After merge: deploy steps, monitoring, stakeholder notifications

# Type-specific additions
- Feature: link to spec, flag name (default OFF), metrics to monitor
- Bug fix: root cause, reproduction steps, regression test
- Hotfix: impact, timeline, immediate fix, follow-up plan
- Refactor: motivation, behavior-unchanged validation, risk assessment

# Large PR strategy
- Vertical slice: one user-facing behavior per PR
- Prepare/activate: inert change PR first, then flag-on PR
- Target < 400 lines changed; use stacked PRs for larger features

Back to skills More skills