Pr Description SkillSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

evals/
evals.json            # top-level manifest (gates, keyword lists)
triggers.json         # 18 trigger items (9 fire / 9 no-fire),
# ~60/40 train/val split
content/
auth-refactor.json  # cross-cutting refactor scenario + rubric
docs-only.json      # docs-only PR scenario + rubric
dep-bump.json       # mechanical dep bump scenario + rubric
fixtures/
__with_skill.md      # representative output produced
# under the SKILL.md guidance
__without_skill.md   # representative output produced
# without the skill loaded
results/
.gitkeep            # tracked sentinel
.json      # one file per run (gitignored)
README.md             # this file

python .apm/skills/pr-description-skill/scripts/run_evals.py

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: pr-description-skill
description: >-
  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.
---

# PR Description Skill -- Anchored, Concise, Validated PR Bodies

## When to use

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:

1. **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`.
2. **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.

1. **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.

   Anchor: Agent Skills,
   ["agents pattern-match well against concrete structures"](https://agentskills.io/skill-creation/best-practices).

2. **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.

   Anchor: PROSE,
   ["Grounding outputs in deterministic tool execution transforms probabilistic generation into verifiable action."](https://danielmeppiel.github.io/awesome-ai-native/docs/prose/).

3. **Cite-or-omit.** If a WHY-claim cannot be backed by a verbatim
   quote, drop it or soften to a tradeoff statement. Never invent
   justification.

   Anchor: Agent Skills,
   ["Add what the agent lacks, omit what it knows"](https://agentskills.io/skill-creation/best-practices).

4. **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.

   Anchor: Agent Skills,
   ["agents pattern-match well against concrete structures"](https://agentskills.io/skill-creation/best-practices).

5. **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.

   Anchor: PROSE,
   ["Favor small, chainable primitives over monolithic frameworks."](https://danielmeppiel.github.io/awesome-ai-native/docs/prose/).

6. **Single artifact, no fluff.** One markdown file. No marketing
   tone, no self-congratulation. TL;DR is at most four sentences.

   Anchor: Agent Skills,
   ["When you find yourself covering every edge case, consider whether m

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.