PR Description With Evidence and Merge Risk

What it does

The source defines three sections: Summary, Evidence and Merge Danger. A summary may use a small diff sketch, call tree, component tree, pseudocode or Mermaid diagram; the choice depends on what explains the change. Evidence pairs an observed before state with the resulting after state. Merge Danger names reversibility and blast radius. Project glossary language keeps the description aligned with reviewers’ domain. The skill credits Dex Horthy and Humanlayer’s show-me workflow as its upstream inspiration.

When to use it

• Explain a UI change with matched screenshots and a compact component sketch.
• Describe a bug fix through a failing and passing behavior check.
• Make migration reversibility and affected consumers visible during review.

Step-by-step workflow

1. Read the final diff, originating requirement and project glossary.
2. Choose the smallest visual that explains the changed behavior or ownership.
3. Pair actual before and after observations without inventing test output.
4. Assess whether rollback is straightforward and identify the affected scope.
5. Write the three-section body and verify every claim against available evidence.

Example request

Use pr to draft the description for our invoice deduplication change. Show a minimal pseudocode sketch of the idempotency check. Use the recorded duplicate-import failure and passing public API test as before-and-after evidence. Explain rollback behavior and whether existing invoices require migration. Use our glossary. Draft the body locally; do not open or update a pull request. Mark missing evidence explicitly.

Worked example

A deduplication PR can show that a repeated request now returns the existing invoice before a second insert. Evidence should identify the real test and its observed outcome, not claim all production duplicates are solved. If a new unique constraint requires cleaning historical rows, that data operation changes the reversibility discussion. A reviewer should see the operational consequence in Merge Danger rather than infer it from a diagram. If screenshots add nothing to a backend fix, use execution evidence.

What you get

A reviewable PR body with Summary, Evidence and Merge Danger sections.

How to evaluate the result

• Verify evidence comes from the actual change.
• Check the visual omits no consequential boundary.
• Confirm reversibility and blast radius reflect migrations and consumers.

What you need

The final diff, actual validation results, relevant screenshots when useful, project terminology and knowledge of deployment effects.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

The template cannot prove a change is safe. Missing before evidence or unknown rollback behavior must stay explicit. Writing a body does not authorize publishing a PR. Upstream credits should be retained when reusing the source itself.

Related workflows

• Use code-review before writing the description.
• Use retro after completion to improve future evidence collection.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Reviewed SKILL.md (immutable commit)
• Publisher README: setup and compatibility
• Reviewed MIT license