pr-description

PR Description — Context-First Reviewer Narrative

Write PR descriptions that are precise, reviewer-friendly, and narrative: context first, grouped changes second, rationale and notes last. The goal is to make a reviewer understand why this exists, what changed, where to focus, and what risks or edges matter without reading every file first.

Good PR descriptions have a clear thesis, enough background to make the diff obvious, concrete examples where shape or behavior changed, explicit tradeoffs, and direct risk/edge callouts. They respect the reviewer's time by separating narrative from mechanics and leaving routine test status to CI/CD.

This style is calibrated to the user's preferred PR shape. Open directly with the context paragraph—do not add a ## Context heading:

<Context paragraph explaining why the PR exists.>

## What changed

### Focused subsystem / behavior

## Why

## Notes

Use this structure as a default, but shrink or expand it to fit the PR.

Core Style Principles

1. Start directly with context, not a heading or implementation. The opening paragraph should explain the situation, constraint, or bug that made the change necessary. Never prefix it with a Context heading.
2. Tell a story. Move from problem → approach → important details → reason/tradeoffs → proof.
3. Group by concept, not file. Use ### subsections for meaningful units of change, such as migration, storage model, API behavior, UI state, tests, or rollout.
4. Be concrete. Include names of important commands, paths, config keys, routes, state keys, data shapes, or user-visible behavior when they help review.
5. Show before/after when it clarifies. Use small code/text blocks for schema, filesystem layout, API shape, CLI output, or behavior changes.
6. Make ownership and boundaries explicit. Call out what is included, excluded, global vs scoped, backend vs frontend, migration vs steady state, etc.
7. Let CI/CD own routine validation. Do not include a default validation/testing section. Mention manual verification only when it is review-relevant and not covered by CI.
8. Surface risk and reviewer focus. Put rollback, compatibility, migration, known gaps, manual checks, and contract changes in ## Notes or ## Risks.
9. Avoid generic checklist filler. Prefer compact prose and purposeful bullets over templates like "Summary / Testing" when more context is needed.
10. Keep it reviewable. Long PRs can be detailed; small PRs should be concise.