pr-description

The single source of truth for how every Agent Forge PR body is written. All ship paths (/ship, /forge-ship, /forgemaster's ship phase) compose the PR body from this template and validate it before gh pr create.

The template lives at references/pr-template.md — edit that file to change the standard; everything else references it.

When to Use

• Any time a PR is opened or its body edited from this harness.
• When the user asks for "the PR format / template" or to check that a PR body conforms.

Required sections

Every PR body MUST contain these H2 headings, each filled (no leftover placeholders):

Section	Holds
## What Changed	The change in plain language + concrete edits
## Why It's Needed	Motivation: the problem, need, or bug it addresses
## How It Was Tested	Gates run, automated suites, manual steps
## Test Evidence	Real proof — pasted command output / counts, not a claim
## Risk & Rollback	Blast radius and the undo path
## Linked Issues & AC Trace	Closes <beads-id> + acceptance-criterion → evidence table

The first four are the harness baseline (what / why / how-tested / evidence). Risk & Rollback and Linked Issues & AC Trace are the harness additions — they make a PR reviewable (knowable blast radius) and traceable (every acceptance criterion mapped to evidence), matching the Beads-first, test-evidence rules in CLAUDE.md.

Process

1. Start from the template

cp .claude/skills/pr-description/references/pr-template.md .tmp/work/pr-body.md

Fill every section. For a /forge-ship run, the ship report (reports/<slug>-ship.md) already contains the narrative and walkthrough — map it into the template sections rather than duplicating prose. Paste actual test output into ## Test Evidence; never green-wash.

2. Validate before creating the PR

bun run .claude/skills/pr-description/scripts/check-pr-body.ts .tmp/work/pr-body.md

The validator emits { ok, data: { present, missing, empty }, error } and exits non-zero if any required section is missing or left as a placeholder. Fix and re-run until ok: true.

3. Open or update the PR

gh pr create --base <base> --title "<title>" --body "$(cat .tmp/work/pr-body.md)"
# or, on an existing PR:
gh pr edit <n> --body "$(cat .tmp/work/pr-body.md)"

To check a PR that already exists:

gh pr view <n> --json body -q .body | bun run .claude/skills/pr-description/scripts/check-pr-body.ts -

Exit Criteria

• PR body contains all six required sections, each filled.
• ## Test Evidence holds real output, not a promise.
• check-pr-body.ts reports ok: true.