From e974c1985b18c004ee723862ee8b701c530f7d45 Mon Sep 17 00:00:00 2001
From: mbeaulne <matt.beaulne@gmail.com>
Date: Mon, 2 Nov 2026 17:35:32 -0500
Subject: [PATCH] Make pull request descriptions easier to understand

---
 .agents/skills/pr-description          |  1 +
 .claude/skills/pr-description/SKILL.md | 48 ++++++++++++++++++++++++++
 .github/PULL_REQUEST_TEMPLATE.md       | 26 ++++++++++----
 3 files changed, 69 insertions(+), 6 deletions(-)
 create mode 120000 .agents/skills/pr-description
 create mode 100644 .claude/skills/pr-description/SKILL.md

diff --git a/.agents/skills/pr-description b/.agents/skills/pr-description
new file mode 120000
index 0000000000..90c568e51d
--- /dev/null
+++ b/.agents/skills/pr-description
@@ -0,0 +1 @@
+../../.claude/skills/pr-description
\ No newline at end of file
diff --git a/.claude/skills/pr-description/SKILL.md b/.claude/skills/pr-description/SKILL.md
new file mode 100644
index 0000000000..7486f8e07b
--- /dev/null
+++ b/.claude/skills/pr-description/SKILL.md
@@ -0,0 +1,48 @@
+---
+name: pr-description
+description: Draft or rewrite pull request titles and descriptions in plain language using the repository template. Use when preparing a new PR description or updating an existing one.
+---
+
+# PR Descriptions
+
+Use the [repository PR template](../../../.github/PULL_REQUEST_TEMPLATE.md) for
+section order and prompts. Keep the description understandable to someone who does
+not write code and has not seen the conversation.
+
+## Establish the facts
+
+- Read the changes against the actual base branch and enough surrounding code to
+  understand the behavior before and after. Do not rely on commit messages alone.
+- For an existing PR, read its current description. Preserve useful screenshots,
+  test evidence, issue links, and dependencies.
+- For a stack, describe only this PR's changes against its actual parent and name
+  any dependency. Do not claim behavior delivered only by another PR.
+
+## Write the description
+
+- Give the title and opening explanation a clear purpose in everyday language.
+  Explain who benefits, what happens today, and what will happen after the change.
+- Keep each section short. A small change may need only a sentence per section.
+  Avoid file inventories, jargon, repeated points, and the history of the work.
+- Include technical details when they help reviewers understand behavior, a
+  tradeoff, or an important limitation. Explain unfamiliar terms.
+- Do not invent user-facing problems for internal work or add unsupported claims.
+  Use a closing issue reference only when this PR actually resolves the issue.
+
+## Make testing concrete
+
+- Start with numbered UI steps using real screen and control names and visible
+  expected results. Include relevant existing behavior that should still work.
+  Do not replace UI steps with commands merely because the UI was not tested.
+- Assume the normal frontend and backend are already running. Mention only extra
+  services or unusual setup, and call out when verification needs no backend.
+- When there is no meaningful UI route, explain why and give the smallest useful
+  commands or other steps, including what success looks like.
+- Write testing instructions directly, without a preamble saying they are
+  suggestions or were not run for the description. Add a short factual note for
+  relevant checks actually performed or specific verification gaps. Never claim a
+  check ran or passed without evidence; automated checks do not establish that
+  the UI was tested.
+
+Keep drafts in chat unless the user authorizes creating or updating the PR. This
+skill does not itself authorize publishing or changing other PR metadata.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 2865b7dbfa..d8fa6206ad 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,6 +1,24 @@
-## Description
+<!-- Write in plain language for someone who has not seen the conversation. Keep each section short and include technical details only when they help explain the change. -->
 
-<!-- Please provide a brief description of the changes made in this pull request. Include any relevant context or reasoning for the changes. -->
+## Intent
+
+<!-- What should this change achieve, and who does it help? -->
+
+## Current behavior
+
+<!-- What happens today, and what is missing or difficult? For internal changes, describe the limitation without inventing a user-facing problem. -->
+
+## What changes
+
+<!-- What happens after this change, and how does it address the limitation? Explain the result rather than listing edited files. -->
+
+## How to test
+
+<!-- Give numbered actions and the expected result of each, using the product UI when possible. Assume the normal frontend and backend are running. Mention only extra services, unusual setup, or when no backend is needed. If there is no UI route, explain why and give specific commands or other steps with expected results. -->
+
+1.
+
+<!-- Add a short factual note for relevant checks actually run or specific verification gaps. Skip generic disclaimers about drafting the description or the steps being suggestions. Never claim a check ran or passed without evidence. -->
 
 ## Related Issue and Pull requests
 
@@ -50,10 +68,6 @@ Split the lines added/removed against the PR's base branch (`git diff --numstat
 
 <!-- Include any screenshots that might help explain the changes or provide visual context -->
 
-## Test Instructions
-
-<!-- Detail steps and prerequisites for testing the changes in this PR -->
-
 ## Additional Comments
 
 <!-- Add any additional context or information that reviewers might need to know regarding this PR -->