Use this skill to write the PR description (PR body) for any pull request opened against microsoft/apm. Produces one self-sufficient GitHub-Flavored Markdown artifact: TL;DR, Problem (WHY), Approach (WHAT), Implementation (HOW), 1-3 validated mermaid diagrams, explicit trade-offs, validation evidence, and a How-to-test section -- with every WHY-claim backed by a verbatim quote from PROSE or Agent Skills. Activate when the user asks to "write a PR description", "draft a PR body", "open a PR", "fill in the PR template", or any equivalent.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use this skill to write the PR description (PR body) for any pull request opened against microsoft/apm. Produces one self-sufficient GitHub-Flavored Markdown artifact: TL;DR, Problem (WHY), Approach (WHAT), Implementation (HOW), 1-3 validated mermaid diagrams, explicit trade-offs, validation evidence, and a How-to-test section -- with every WHY-claim backed by a verbatim quote from PROSE or Agent Skills. Activate when the user asks to "write a PR description", "draft a PR body", "open a PR", "fill in the PR template", or any equivalent.
Trigger this skill on any of the following intents:
"write a PR description"
"draft a PR body"
"open a PR" / "open this PR" / "let's open the PR"
"fill in the PR template"
"summarize this branch as a PR"
"create the PR write-up"
Reusable for any PR against microsoft/apm. The output is one
markdown file that the orchestrator pastes into
gh pr create --body-file or surfaces to the maintainer.
Output charset rule (read this first)
The repo-wide encoding rule at
.github/instructions/encoding.instructions.md constrains
source files and CLI output to printable ASCII because Windows
cp1252 terminals raise UnicodeEncodeError on anything else. PR
comments are NOT source code and NOT CLI output -- they are rendered
by GitHub's Primer engine, which expects UTF-8 GitHub-Flavored
Markdown.
Two distinct rules therefore apply:
Source files in this bundle (SKILL.md, assets/*) MUST
stay ASCII. They live in the repo and are subject to
.github/instructions/encoding.instructions.md.
The PR body output the skill produces MUST be UTF-8
GitHub-Flavored Markdown. Use em dashes, smart punctuation,
alerts, collapsibles, task lists, and Unicode where it improves
readability. Mermaid diagram labels MAY use Unicode -- there is
no constraint here. The output is consumed by GitHub's renderer,
not by a Windows terminal.
A previous version of this skill incorrectly required ASCII in the
PR body. That made the output unreadable: no alerts, no collapsibles
for long evidence, no em dashes, no smart quotes. Reviewers had to
scroll through hundreds of flat lines instead of scanning a body
shaped by GFM features.
Concision targets (hard ceilings)
The skill aims for 150-220 lines for a typical PR body. 300+
lines is a smell, not a virtue. If your draft exceeds 250 lines,
run a tightening pass: every sentence that does not change the
reviewer's understanding must be cut.
Per-section ceilings (enforced by assets/section-rubric.md):
Section
Ceiling
TL;DR
2-4 sentences
Problem (WHY)
max 6 bullets, max 3 quoted anchors total
Approach (WHAT)
a table OR 3-7 bullets; may be skipped if PR is purely additive (say "additive: see Implementation")
Implementation (HOW)
one short paragraph per file, OR a table; no prose walls
Diagrams
1-3 mermaid blocks; every diagram preceded by a one-sentence legend
Trade-offs
3-5 bullets; mechanical PRs may be 1-2
Benefits
3-5 numbered items, each measurable
Validation
copy-paste real command output; do not narrate
How to test
max 5 numbered steps
Long verbatim quote blocks, full file listings, and full validation
transcripts SHOULD live inside <details> so the body stays
scannable.
Core principles (with quoted anchors)
Each rule the skill enforces is backed by a verbatim quote from one
of the two reference docs. If a rule below cannot be backed by a
quote, it is downgraded to a "should" with the reason given.
Self-sufficient body. A reviewer must be able to read the PR
body and form an opinion without opening any other doc, issue,
or chat. Every WHY-claim cites the source doc inline; every
named file is qualified with what changed in it; every diagram
has a one-sentence legend.
Anchored: every WHY-claim cites its source. Every claim of
the form "this violates X" or "this satisfies Y" is followed by
a verbatim quoted phrase wrapped in a hyperlink to the source
page. Reproduce quotes character-for-character; do not paraphrase
inside link text.
Visual aid where structure is non-trivial. Any change that
touches more than one file or alters control flow SHOULD include
at least one mermaid diagram. Add a second only when the
relationships are non-trivial. Never add a third unless it earns
its place. Each diagram MUST be preceded by a one-sentence legend.
Trade-offs explicit. Address every non-obvious decision
(option chosen vs option rejected). For mechanical PRs this
section may be 1-2 bullets. For cross-cutting changes, surface
the rejected alternatives.
Use <details open> only when the content answers the most
likely first reviewer question.
Task lists for "How to test" sections:
- [ ] Apply label, observe X.
Tables with alignment: | col | :---: | ---: | for matrices.
Permalink references to specific lines in the diff:
https://github.com/microsoft/apm/blob/<sha>/path#L12-L34.
Long verbatim quote blocks, full file listings, and full validation
transcripts SHOULD live inside <details> so the body stays
scannable.
Required body structure
#
Section
Purpose
1
Title line
Imperative summary; first line <verb>(<scope>): <summary>, max 100 chars
2
TL;DR
2-4 sentence executive summary
3
Problem (WHY)
Observed failure modes; max 6 bullets, max 3 quoted anchors
4
Approach (WHAT)
Table or 3-7 bullets; may say "additive: see Implementation"
5
Implementation (HOW)
One short paragraph per file or a table
6
Diagrams
1-3 validated mermaid blocks, each with a legend; diagram type chosen per intent (assets/mermaid-conventions.md)
7
Trade-offs
3-5 bullets (1-2 if mechanical)
8
Benefits
3-5 numbered, measurable items
9
Validation
Real command output, ideally inside <details> if long; MUST include the Scenario Evidence subsection (assets/scenario-evidence-rubric.md) for any behavior-change PR -- maps each user-promise scenario this PR touches to the test that proves it works, tagged with the APM principle the scenario serves
10
How to test
Max 5 numbered or task-list steps
The Trade-offs (7) and How to test (10) sections are non-skippable
for any PR that changes more than docs.
Activation contract -- inputs the orchestrator MUST gather first
Before invoking this skill, the orchestrator MUST have collected
all of the following. The skill MUST NOT invent facts not present
in these inputs.
Input
Source
Required
Branch name (head)
git rev-parse --abbrev-ref HEAD
yes
Base ref
usually main; ask if unclear
yes
List of files changed
git diff --name-status <base>...HEAD
yes
Actual diff
git diff <base>...HEAD
yes
Commit messages on the branch
git log --no-merges <base>..HEAD --oneline
yes
CHANGELOG entry, if any
inspect CHANGELOG.md Unreleased section
yes
Linked issue / motivation
user-provided or referenced in commits
yes
Validation evidence
output of apm audit --ci, uv run pytest, or equivalent
yes
Scenario-test mapping
author-supplied or derived from diff: per user-promise scenario the PR touches, the test path proving it, plus the APM principle the scenario serves (taxonomy in assets/scenario-evidence-rubric.md)
conditional (required for any behavior-change PR; may be skipped for docs-only / asset-bump / pure-refactor per the rubric's skip clause, with the skip case stated in trade-offs)
Mirror parity check, if applicable
apm install --target copilot output
conditional
If any required input is missing, the orchestrator MUST stop and
collect it. This is a Progressive Disclosure boundary:
"Context arrives just-in-time, not just-in-case.".
Do not load assets/pr-body-template.md until the table above is
complete.
Execution checklist
Run these steps in order. Tick each before moving on.
Confirm every row of the activation contract is filled in.
Defense-in-depth gate: before drafting the body, confirm the
repo's lint contract is green (canonical commands and lifecycle
binding live in .apm/instructions/linting.instructions.md). If lint is red,
STOP, fix, re-run; a PR body claiming green CI while lint fails
is a credibility tax we refuse to take on.
Read the diff in full. Identify per-file change summary,
new files, deleted files, behavior changes at module
boundaries.
Fill in the template top-to-bottom using only facts from
the activation contract. Every WHY-claim gets a verbatim
quoted anchor. If you cannot anchor a claim, drop it.
Generate 1-3 mermaid diagrams. Before drafting any block,
load assets/mermaid-conventions.md to pick the right
diagram type per intent (sequenceDiagram for execution flow,
flowchart LR for pipeline / architecture, stateDiagram-v2 for
state machines) and apply the boxing convention for NEW
behavior. Add a one-sentence legend above each diagram.
Validate every mermaid block deterministically (see
below). Do NOT save the draft until every block validates.
Run the line-count check. If the body exceeds 250 lines,
tighten until it fits 150-220.
Write the final body to a single file path provided by the
orchestrator (default: .git/PR_BODY.md or
session-state-relative). Return the path; do not paste the
body inline unless explicitly asked.
Mandatory mermaid validation step
Run every mermaid block in the draft through mmdc and refuse to
save until all pass.
# Extract mermaid blocks and validate each one.# Requires: npx --yes -p @mermaid-js/mermaid-cli mmdc (one-shot, no global install needed)
awk '/^```mermaid/{n++; f=outdir"/diag"n".mmd"; getline; while($0 != "```") {print > f; getline}}' outdir=/tmp/mermaid-check pr-body-draft.md
for f in /tmp/mermaid-check/diag*.mmd; do
npx --yes -p @mermaid-js/mermaid-cli mmdc -i "$f" -o "${f%.mmd}.svg" --quiet || { echo"INVALID: $f"; exit 1; }
done
If mmdc reports any error, fix the diagram and re-run. The skill
MUST NOT save the draft until every mermaid block validates.
Diagram type and pitfalls reference
The full diagram-type-by-intent table, canonical templates, and the
GitHub-renderer gotcha list (mmdc does NOT always catch GitHub
rejections) live in assets/mermaid-conventions.md. Load it whenever
a PR body needs a mermaid block.
Critical drift-known gotcha (the one most likely to bite, captured
inline because it is not obvious from mmdc output):
Square brackets in flowchart edge labels MUST be quoted.A -->|[EXEC] work| B parses on mmdc but is rejected by
GitHub's renderer (Expecting 'TAGEND', ..., got 'SQS'). Quote
the label: A -->|"[EXEC] work"| B. The same rule applies to
parentheses, colons, slashes, and pipes in edge labels.
For everything else (semicolons in classDiagram links, note right of closing rules, round brackets in node labels, inline
:::cssClass failing in classDiagram on GitHub), see
assets/mermaid-conventions.md.
Output contract
Exactly ONE markdown file is produced.
The file is UTF-8 GitHub-Flavored Markdown. Em dashes, smart
quotes, Unicode in mermaid labels, alerts, and collapsibles are
all permitted and encouraged where they improve readability.
Every mermaid block has been validated by mmdc and renders
without error.
The cite-or-omit rule applies absolutely.
The TL;DR is at most four sentences.
The body ends with the trailer:
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Anti-patterns flagged -- refuse these
Posting unvalidated mermaid. A parser error renders as raw
code on GitHub and signals carelessness. Validate every block
before saving.
Pasting commit messages as the body. Commit messages are inputs,
not output.
Marketing tone or self-congratulation ("this is a great
improvement", "significantly enhances", "best-in-class"). Strip
on sight.
Diagrams without a legend, OR diagrams that fail mmdc.
A TL;DR longer than four sentences.
Skipping any required section because "the PR is small". A small
PR can have a one-line Implementation per file, but the section
header must still be present.
Restating the diff line-by-line in Implementation. That is what
the Files Changed tab is for.
Quoting a doc out of context. The self-check pass must verify
that the quoted phrase actually supports the claim.
Forcing ASCII-only on the PR body. That rule applies to
source files and CLI output, not to Primer-rendered markdown.
See "Output charset rule" above.
Gotchas
Do not restate the diff. Implementation is for intent, risk,
and decisions -- not a textual re-rendering of the patch.
Do not quote out of context. Re-read the surrounding paragraph
of the source doc before pasting a quote.
Verify the source URL still serves the quoted text. If the
doc has been edited and the phrase no longer appears verbatim,
drop the citation or find a new anchor.
A doc-only PR still needs TL;DR, Problem, Validation, and
How-to-test. "The PR is trivial" is not an exemption.
Long evidence belongs in <details>. Reviewers should be
able to read the whole body in a single screen-and-a-half scroll
and expand evidence on demand.
