Prompt Workshop
Why it is written this way
Tap a block to see its paragraph
You are a software engineer renowned for writing exceptionally clear, considerate pull request descriptions. Your top priority is respecting the reviewer's time.
Assume the reader lacks background context and is seeing these changes for the first time today. Here is how the changes were verified: {{testing methodology guide}}
Read the notes and file list below, then write the pull request description. Emphasize *why* the changes were necessary before detailing *what* changed.
Format: Organize the description into five clear sections: "Why this change is needed", "Summary of changes", "Key review points", "How to verify", and "Out of scope". Keep each of the first two sections under three lines, format "Key review points" as a bulleted list with up to 3 items, and include a single-sentence summary at the very top.
Do not fabricate performance metrics, issue tracking numbers, or release schedules not mentioned in the notes. If any critical detail is ambiguous, list up to 3 clarifying questions under an "Author Action Required" section at the bottom.
Work task details: """ {{work task detail}} """
Modified file list: """ {{modified file list}} """
- Role Who answers ×1
- Material What the AI needs to know ×3
- Work What to do, and how ×1
- Output What comes back, in what shape ×2
When writing PR descriptions, most engineers only describe what changed. However, the file list and diff already show what changed. What reviewers cannot see is why a specific approach was chosen; without that context, the review stalls with questions like "Why did you do it this way?"
Read the full explanation · 4 paragraphs
Setting the role as a developer who prioritizes reviewer time controls the output length. Without this instruction, AI tools tend to generate a verbose paragraph for every single file, which reviewers rarely read in full. The context stating the reader is seeing this for the first time eliminates internal jargon and unhelpful abbreviations.
The five structured sections in the format form the core of this prompt. In particular, "Key review points" and "Out of scope" prevent back-and-forth review loops. The former directs the reviewer's attention to critical logic, while the latter pre-emptively answers "Why didn't you fix this other issue as well?"
Explicitly banning hallucinated details is critical when using AI for PR descriptions. Models often invent plausible metrics or issue ticket numbers that reviewers might accept as real facts. Directing ambiguities into an "Author Action Required" section keeps the description reliable.
Finally, highlighting the testing methodology upfront addresses the most common review question: "Did you test this locally?" Clear verification steps allow reviewers to reproduce the checks quickly or spot edge cases.
Unfamiliar terms? See Aha AI: role-prompting, context-window
Compared with a bad example
Write a PR description for this.
(Pasted list of changed files)
This generates a dry, line-by-line summary of file names that provides no more value than reading git diff directly. Without the background rationale, reviewers have to message the author for clarification. Lacking specific focal points, reviews often degrade into trivial typo checks or passive rubber-stamping.
Variations
When deploying an urgent hotfix
Use this for hotfixes and incident responses where speed is crucial. Rollback steps are the most critical piece of an urgent patch.
Show prompt
Write a concise, emergency pull request description based on the notes below. Include only: a one-sentence summary, a two-line explanation of why this is urgent, verification steps, and rollback instructions. Do not include any other sections. Here is how it was tested: {{testing methodology guide}}
""" {{work task detail}} """
When seeking architectural feedback
Use this when submitting work with design uncertainties. Framing explicit questions right in the PR body ensures the review starts on critical architectural decisions.
Show prompt
Review the task details below, identify the architectural trade-offs or decisions that carry uncertainty, and convert them into up to 3 targeted questions for the reviewer. For each question, include a one-line summary of the alternatives considered and the reason for the current choice. Do not decide the answers yourself.
""" {{work task detail}} """
Last updated 2026-09-02 · Found a mistake? Let us know