Add structured PR template and write-pr-description skill

.claude/commands/write-pr-description.md

@@ -0,0 +1,77 @@
+---
+description: >
+  Write or improve a GitHub pull request description. Use when the user asks
+  to "write a PR description", "improve the PR description", "update the PR
+  body", or provides a PR URL and asks for a better description.
+  Keywords: PR description, pull request summary, PR body, PR writeup.
+allowed-tools: [Read, Glob, Grep, Bash, ToolSearch]
+---
+
+# Write PR Description
+
+Generate a structured PR description that explains **why** the change exists,
+not just what files were touched.
+
+## When to use
+
+- The user provides a PR URL and asks to write or improve its description.
+- The user asks to draft a PR description for the current branch.
+- An agent needs to open a PR and wants a high-quality description.
+
+## Workflow
+
+### Phase 1: Gather context
+
+Collect all the information needed to understand the change:
+
+1. **Read the PR metadata** — title, current description, author, branch name.
+2. **Read the full diff** — understand every file changed, every function added
+   or removed, every signature change. Do not skip files.
+3. **Read surrounding code when needed** — if the diff modifies an interface or
+   a struct, read the full file to understand how the change fits into the
+   existing architecture.
+4. **Check for linked issues or docs** — the PR or commit messages may
+   reference issues, design docs, or RFCs that explain motivation.
+
+### Phase 2: Analyze the change
+
+Before writing, answer these questions internally:
+
+- **What was the status quo before this PR?** What limitation, bug, or missing
+  capability existed?
+- **Why is this change needed now?** What concrete problem does it solve? Who
+  benefits?
+- **What are the key design decisions?** Why was this approach chosen over
+  alternatives?
+- **What is the new API surface?** Any new public types, functions, or
+  configuration options?
+- **What are the architectural changes?** How does the internal structure
+  change? What moves where? What gets refactored?
+- **Are there behavioral changes?** If not, say so explicitly — this reassures
+  reviewers.
+
+### Phase 3: Write the description
+
+Use the structure defined in `.github/PULL_REQUEST_TEMPLATE.md` as the
+template. The tone should be direct and technical. Write for a reviewer who is
+familiar with the codebase but has not seen this change before.
+
+**Key principles:**
+
+- **Lead with why, not what.** The diff already shows the what. The description
+  should explain the reasoning that is not visible in the code.
+- **Be specific.** Instead of "improves extensibility", say "allows internal
+  tools to compose their own auth chain from individual credential strategies".
+- **Name things.** Reference actual types, functions, files, and config fields.
+  Use backticks for code references.
+- **State non-changes explicitly.** If the PR is a refactor with no behavioral
+  change, say "No behavioral changes. Existing users are unaffected." This is
+  valuable information for reviewers.
+- **Keep the summary to one or two sentences.** It should be scannable.
+- **Use the motivation section to tell a story.** What was the problem? Why
+  couldn't it be solved before? What does this PR unlock?
+
+### Phase 4: Update the PR
+
+Use the GitHub MCP tools or `gh` CLI to update the PR body with the new
+description. Confirm with the user before pushing if unsure.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,28 +1,74 @@
-## What changes are proposed in this pull request?
+<!--
+  This template provides a recommended structure for PR descriptions.
+  Adapt it freely — the goal is clarity, not rigid compliance.
+  The three-section format (Summary / Why / What Changed) helps reviewers
+  understand the change quickly and makes the PR easier to revisit later.
+-->
 
-Provide the readers and reviewers with the information they need to understand
-this PR in a comprehensive manner. 
+## Summary
 
-Specifically, try to answer the two following questions:
+<!--
+  One or two sentences describing what this PR changes and what it enables.
+  Focus on the effect, not the implementation details.
 
-- **WHAT** changes are being made in the PR? This should be a summary of the 
-  major changes to allow the reader to quickly understand the PR without having
-  to look at the code. 
-- **WHY** are these changes needed? This should provide the context that the 
-  reader might be missing. For example, were there any decisions behind the 
-  change that are not reflected in the code itself? 
+  Example:
+    Extracts the credentials chain iteration logic into a reusable
+    `NewCredentialsChain` constructor so that internal tools can compose
+    their own authentication chains from individual credential strategies.
+-->
 
-The “why part” is the most important of the two as it usually cannot be 
-inferred from the code itself. A well-written PR description will help future
-developers (including your future self) to know how to interact and update your
-code.
+## Why
+
+<!--
+  Explain the problem that motivated this change. A reviewer who reads only
+  this section should understand why the PR exists and what problem it solves.
+
+  - Start with the status quo: how things work today and what limitation exists.
+  - Explain who is affected and what they cannot do (or must work around).
+  - If alternatives were considered and rejected, briefly mention why.
+  - End with how this PR addresses the gap.
+
+  The "why" is the most important part of a PR description — it usually
+  cannot be inferred from the code itself.
+-->
+
+## What changed
+
+### Interface changes
+
+<!--
+  New or modified public API surface: types, functions, configuration options.
+  Use backticks for code references. Write "None." if there are no changes.
+
+  Example:
+    - **`NewCredentialsChain(...CredentialsStrategy) CredentialsStrategy`** —
+      Takes an ordered list of credential strategies and returns a strategy
+      that tries them in sequence.
+-->
+
+### Behavioral changes
+
+<!--
+  User-visible behavior changes: different defaults, changed error messages,
+  new side effects, performance characteristics. Write "None." if this is a
+  pure refactor — this explicitly reassures reviewers.
+-->
+
+### Internal changes
+
+<!--
+  Refactoring, file moves, implementation details, test infrastructure.
+  Things that don't affect the public API or user-visible behavior.
+-->
 
 ## How is this tested?
 
-Describe any tests you have done; especially if test tests are not part of
-the unit tests (e.g. local tests).
+<!--
+  Describe any tests you have done, especially tests that are not part of
+  the unit tests (e.g. local tests, integration tests, manual verification).
 
-**ALWAYS ANSWER THIS QUESTION:** Answer with "N/A" if tests are not applicable
-to your PR (e.g. if the PR only modifies comments). Do not be afraid of 
-answering "Not tested" if the PR has not been tested. Being clear about what 
-has been done and not done provides important context to the reviewers. 
+  ALWAYS ANSWER THIS QUESTION: answer with "N/A" if tests are not applicable
+  to your PR (e.g. if the PR only modifies comments). Do not be afraid of
+  answering "Not tested" if the PR has not been tested. Being clear about what
+  has been done and not done provides important context to the reviewers.
+-->