Add structured PR template and write-pr-description skill (#673)

## Summary

Replaces the free-form PR template with a structured three-section
format and
adds a `/write-pr-description` Claude command so agents and contributors
can
generate high-quality PR descriptions automatically.

## Why

The current PR template asks contributors to answer "what" and "why" but
provides little structure beyond that. In practice, PR descriptions vary
widely
in quality and organization, making reviews harder and reducing the
long-term
value of the git history.

A structured template (Summary / Why / What Changed) gives contributors
a clear
framework to follow, while the Claude command automates the process for
agent
workflows — reading the diff, analyzing the change, and producing a
description
that follows the template.

## What changed

### Interface changes

None.

### Behavioral changes

None. This only affects PR description authoring, not SDK behavior.

### Internal changes

- **`.github/PULL_REQUEST_TEMPLATE.md`** — Rewritten with three sections
(Summary, Why, What Changed) and ordered sub-sections under "What
Changed":
Interface changes → Behavioral changes → Internal changes. Includes
inline
guidance and examples in HTML comments so it works standalone for
non-Claude
  contributors.
- **`.claude/commands/write-pr-description.md`** — New Claude command
(invocable
via `/write-pr-description`) with a four-phase workflow: gather context
→
analyze → write → update PR. References the PR template as the single
source
  of truth for structure.

## How is this tested?

N/A — no code changes, only documentation and tooling configuration.

NO_CHANGELOG=true

Signed-off-by: Ubuntu <renaud.hartert@databricks.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: renaudhartert-db

.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.
+-->