From 5f330a49389fa821bae64cc0db1a1ce276620f6f Mon Sep 17 00:00:00 2001
From: mbeaulne <matt.beaulne@gmail.com>
Date: Mon, 2 Nov 2026 16:45:16 -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, 67 insertions(+), 8 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 00000000..90c568e5
--- /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 00000000..7486f8e0
--- /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 6bfb01b9..c576ffe0 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,21 +1,31 @@
-Closes #ISSUE_NUMBER
+<!-- 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. -->
 
-<!-- Replace ISSUE_NUMBER with the issue this pull request closes. -->
+<!-- Link a related issue if there is one. Use "Closes #123" only when this PR resolves it. -->
 
-## Description
+## Intent
 
-<!-- Describe what changed and why. Include any context reviewers need. -->
+<!-- What should this change achieve, and who does it help? -->
 
-## Screenshots
+## Current behavior
+
+<!-- What happens today, and what is missing or difficult? For internal changes, describe the limitation without inventing a user-facing problem. -->
 
-<!-- Add screenshots or recordings for user-facing changes. Write "N/A" when not applicable. -->
+## 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
 
-<!-- List prerequisites and the exact steps needed to verify this change. -->
+<!-- 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. -->
+
+## Screenshots
+
+<!-- Add screenshots or recordings for visible changes. Write "N/A" when not applicable. -->
+
 ## Notes
 
-<!-- Add rollout details, follow-up work, known limitations, or anything else reviewers should know. Write "N/A" when not applicable. -->
+<!-- Include dependencies on other PRs, rollout details, or important limitations. For a stack, describe only this PR's changes against its actual parent. Write "N/A" when not applicable. -->