databricks 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:
- Read the PR metadata — title, current description, author, branch name.
- Read the full diff — understand every file changed, every function added or removed, every signature change. Do not skip files.
- 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.
- 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.