From 0cd05bc3d983ef2ff8dd1954161e1e7bb485226b Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Wed, 16 Sep 2026 12:47:16 -0700
Subject: [PATCH] docs(contributing): state what a PR description must cover
 (#21080)

AGENTS.md said nothing about writing PRs, and the template's section
comments could be satisfied without ever telling a reviewer what changed
for the user or which mechanism moved. Name the same four requirements in
both places: no jargon, user-facing before/after, the mechanism, and why
over the alternatives.
---
 .github/pull_request_template.md |  8 ++++----
 AGENTS.md                        | 11 +++++++++++
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index e0bbc7da303..9d7a73a6b88 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,14 +1,14 @@
 ## ELI5
 
-<!-- Simple high-level explanation -->
+<!-- Simple high-level explanation, in plain language. No jargon. -->
 
 ## What Changed
 
-<!-- Describe the change clearly and keep scope tight. -->
+<!-- Describe the change clearly and keep scope tight. Cover the before and after as the user experiences it, and the mechanism you changed — not just the symptom. -->
 
 ## Why
 
-<!-- What problem does this solve, and why is this approach right? -->
+<!-- What problem does this solve, and why is this approach better than the alternatives you considered? -->
 
 ## Linked Issue
 
@@ -47,7 +47,7 @@ Ensure no issues in: Security, Cross-platoform support (Linux, Windows, Mac), Re
 ## Checklist
 
 - [ ] This PR is small and focused
-- [ ] I explained what changed and why (including ELI5)
+- [ ] I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
 - [ ] Before/after screenshots or videos attached for UI changes, or `N/A` with reason
 - [ ] Self-reviewed for correctness, security, and performance
 - [ ] Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
diff --git a/AGENTS.md b/AGENTS.md
index 664d986da13..99c56e74108 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -48,6 +48,17 @@ Avoid type assertions except `as const`. Unavoidable casts need a line-specific
 - **Lint**: `oxlint`, or `pnpm run check:code-quality:changed` for changed files (full `pnpm lint` is slow); format with `pnpm format`
 - **Design system**: `pnpm run lint:design-system` for the full renderer report (not a gate); the changed-lines gate above is what CI enforces
 
+# Writing Pull Requests
+
+Fill in [`.github/pull_request_template.md`](./.github/pull_request_template.md), written for a reviewer who has never seen this code:
+
+- No jargon — plain language, no internal shorthand.
+- The before and after as the user experiences it.
+- The mechanism you changed, not just the symptom.
+- Why this approach over the alternatives you considered.
+
+Cover all four concisely. Don't pad or walk the diff.
+
 # Considerations
 
 ## Worktree Safety