dev-pr-description

PR Description Generator

Purpose

A good PR description answers three questions every reviewer has before they read a single line of code: What changed? Why does it exist? How do I verify it? This skill reads the diff and the story together to answer all three — so the reviewer spends their time reviewing, not detective-work.

---

Tool detection

1. Check for active mcp__azure-devops__* tools → $PM_TOOL = ado
2. Check for active mcp__jira__* tools → $PM_TOOL = jira
3. If neither → $PM_TOOL = manual

---

Step 1 — Read the git context

Run the following to understand what changed:

# Changed files and a summary of what moved
git diff --stat HEAD~1..HEAD 2>/dev/null || git diff --stat origin/main..HEAD

# Commit messages on this branch
git log --oneline origin/main..HEAD 2>/dev/null || git log --oneline -10

# Full diff (for understanding the nature of changes)
git diff origin/main..HEAD 2>/dev/null || git diff HEAD~1..HEAD

If git is not available or the branch has no commits yet, ask the developer to describe the changes.

---

Step 2 — Identify the linked story

Look for the work item ID in this order:

1. Branch name — extract a pattern like feature/#1234-, feat/PROJ-456-, dev/1234/, etc.
2. Commit messages — look for #1234, PROJ-456, Refs:, Closes:, or Fixes: references
3. Ask — "Which story does this PR implement? Provide the ID or paste the content."

Then fetch the story:

• ADO: use wit_get_work_item — read title, description, and acceptance criteria
• Jira: use the get-issue tool — read summary, description, and acceptance criteria
• Manual: accept pasted content

Store as $STORY.

---

Step 3 — Map changes to acceptance criteria

Before writing the description, build an internal map:

For each acceptance criterion in $STORY:

• Which files in the diff satisfy it?
• Is it fully satisfied, partially satisfied, or not covered?

Flag any AC that is not covered by the diff — this is either a missing implementation or the AC belongs to a different PR. Surface it: "AC [N] — '[text]' — does not appear to be covered by these changes. Is that intentional?"