* docs(pr): require user-perspective description and surface area
The previous template asked for Summary + Validation, which encouraged
code-perspective descriptions and let user-visible surface changes slip
past review unnoticed. Replace with:
- "Problem" — issue link + motivation
- "What users will see" — first-person user-visible effect
- "Surface area" — 9-item checklist (UI, shortcut, CLI/env, API/contract,
extension point, i18n, top-level dependency, default behavior change, none)
- "Screenshots" — required when UI surface is checked, focused on the
entry point users discover rather than the feature in isolation
- "Validation" — kept, retitled away from "Summary"
Authoritative rules added to AGENTS.md under a new "Pull request expectations"
section so external contributors' agents (Claude Code, Cursor, etc.) pick up
the requirement when reading the repo. CONTRIBUTING.md gets one pointer line
in "Commits & pull requests"; localized CONTRIBUTING variants (zh-CN, de, fr,
ja-JP, pt-BR) are left for follow-up translation PRs per the existing
docs-update workflow.
The existing "Fixes #" prompt is preserved verbatim — that template addition
from #1263 enforces PR-to-issue auto-linking and stays load-bearing.
* docs(pr): broaden dependency surface to dev deps as well
The "New top-level dependency" checkbox narrowed scope to runtime deps,
but CONTRIBUTING.md L239 says "No new top-level dependencies" without
limiting to runtime, and the AGENTS.md rule uses the same broad phrase.
A new devDependency (tool/test/build package) belongs in the same
bytes-vs-benefit explanation, so the checklist item should match.
* docs(pr): add Why and Bug fix verification; scope deps to root package.json
Three follow-up tweaks from review feedback:
1. Rename `## Problem` to `## Why` with a broader prompt that asks
contributors to cover both their own use case (what made them write this
PR today) and the pain being addressed. The old "Problem" framing only
covered user-facing motivations and left no slot for the contributor's
stake — a key signal for triaging external PRs.
2. New `## Bug fix verification` section between Screenshots and Validation,
conditional on the PR being a bug fix. Surfaces the AGENTS.md
"Bug follow-up workflow" red-spec requirement at PR-authoring time
instead of leaving it implicit; asks for the test path and the
red-on-main / green-on-branch confirmation.
3. Clarify the "New top-level dependency" checkbox to specify the **root**
`package.json`. Without that word, contributors in a monorepo could read
the check as applying to any workspace `package.json` (e.g. adding `react`
to `apps/web/package.json` would be in scope) when CONTRIBUTING.md L239's
"small on purpose" rule clearly meant root-level deps only.
AGENTS.md `## Pull request expectations` and CONTRIBUTING.md's pointer
line are updated to match the new section names and add the bug-fix
red-spec expectation.
PRs that omit Fixes #N break the release-time reverse lookup
(issue → closing PR → merge sha → first containing tag), since the
auto-link only fires on the explicit closing keywords. We've been doing
this by hand on recent fixes; codify it so future PRs don't drift.
- Add .github/pull_request_template.md with a Fixes # placeholder so
the link surface is in front of the author by default.
- Add a corresponding bullet to the Bug follow-up workflow in the root
AGENTS.md so the discipline lives next to the methodology that
produces issue-linked work.
