---

name: pr-description-segments description: "Instructions for formatting a PR description. Use when asked to open a PR"

PR description segments

PR descriptions serve two readers fighting for the same real estate: humans need 3-4 plain lines, review agents need dense technical context. Mixing them produces 500-line descriptions nobody reads. Every PR description uses three core segments, with an optional frontend QA section at the top when applicable.

The format

## QA: frontend validation links (frontend-only, top section)

For frontend/user-visible changes, add ## QA as the first section in the PR description. Keep it short and link-only:

• Include local and preview QA links when available, using Markdown links with human-readable text.
• Never expose a full URL as plain text; every link must be [label](url) format.
• If only one environment exists, include only that one.
• Backend-only fixes omit ## QA entirely.

## What & why: the human segment

3-4 plain-language lines, max: what changed, why, and the user/system impact. No file lists, no jargon. This section must stand alone as a Slack announcement.

On customer-facing repos, this section also carries the visual-verification line (the checkbox, its - No visual surface (<reason>) variant, or the stated-verification variant; shapes defined by the visual-verification skill where the repo has adopted it); that line does not count toward the 3-4 line cap.

## Architecture: impact map for the sense-checking reviewer

This segment answers "which of the 3,000 changed lines are business-critical"; separating the critical files from the churn is the point.

• Interfaces and contracts changed: APIs, schemas, events, function signatures.
• Business-critical files touched. Business-critical = breaking it moves money, corrupts or drops data, changes auth/permissions, or breaks a downstream consumer. The file itself must sit on the money/data/auth/consumer path; harm that needs a human intermediary is churn. One line per file: path, why critical, what changed. Everything else is churn; summarize churn as a count ("+38 files: generated fixtures, renames"), never a path list.
• Which flows were tested (and which weren't).
• Needs human eyes: anything neither tests nor agent review verified, named explicitly (this is where the coverage ledger's unverified list surfaces).
• Cross-system blast radius: consumers outside this repo (services, tables, dashboards) that see this change, what breaks if it's wrong, and any deploy/rollback ordering or backward-compat constraints. Always present: write "None (checked )" when there are no external consumers.

Agent context: for review agents and future archaeology

This segment is a single <details><summary>Agent context</summary>...</details> block; the <summary> is its only marker -- there is no separate ## Agent context heading. It renders collapsed. Link to run artifacts instead of pasting output; any paste over ~20 lines becomes a PR comment, not description body. Dense technical detail inside:

• Review coverage ledger: what an agent review already covered; each covered claim links the run or review comment that did the covering, and an unlinked claim doesn't count. Anything it could NOT verify goes in ## Architecture under Needs human eyes, not here.
• Reproduction commands.
• Links to run artifacts (CI runs, test output, query results).

Example

The canonical shape (frontend PRs prepend the optional ## QA block):

## QA

- [Local QA](http://localhost:3000/path-under-test)
- [Preview QA](https://preview.example.com/path-under-test)

## What & why

Dedup transfers at the macro level so downstream models stop double-counting bridged tokens.
Fixes the inflated volume numbers on the tokens dashboard reported by BD.
No schema changes; consumers see lower (correct) totals from next refresh.

## Architecture

- macros/dedup_transfers.sql - new macro, consumed by 14 models
- +31 files: generated re-refs
- Tested: ethereum, base backfill windows. Not tested: solana path.
- Needs human eyes: prod row counts after first refresh
- Blast radius: None (checked warehouse lineage for external consumers)

<details><summary>Agent context</summary>

- Covered: macro logic + 14 call sites reviewed in https://github.com/org/repo/pull/999#pullrequestreview-1
- Repro: dbt build -s +tokens_transfers --defer
- Artifacts: https://ci.example.com/runs/12345

</details>

Mode A: generate

Writing a new PR description: for frontend work with QA environments, start with ## QA; then fill the three core segments top to bottom. Anything that doesn't serve one of the readers doesn't go in.

Sections scale with the PR. A section with nothing load-bearing collapses to a single line: None - <one clause why> (e.g. None - copy-only change, no interface or logic touched); for behavior-neutral changes ## What & why alone is a valid complete description. Trivial means behavior-neutral, not small-diff: a one-line change that alters runtime behavior (a timeout, a limit, a default) earns ## Architecture regardless of diff size. Never pad a section to look filled; the one-liner is a checkable claim, and a false None is a review blocker. If no agent review has run yet, write No agent review yet rather than inventing coverage.

Mode B: re-segment

Given an existing PR's description:

1. Sort its content into the ## QA section (frontend only) and the three core segments, moving each piece to the section whose reader needs it.
2. Content that belongs in none: delete it, and say what was dropped. Exception: machine-parsed content is never deleted or reworded, and what survives is the complete machine-owned block, not just its lines. Position-independent lines - issue-closing keywords (Fixes DWH-123, Closes #45), bot directives that trigger anywhere in a body - stay verbatim below the core segments. Position-dependent blocks - a CI-parsed checklist, a block delimited by HTML comment markers, a template section a bot reads or fills - keep their original structural location byte-identical, surrounding markers and section included; re-segment only the human-authored content around them. Machine-parsed means a bot, CI job, or tracker consumes it; a plain GitHub task list nothing consumes is content, and gets sorted or dropped like any other content. Exception, convention lines: lines another skill mandates into a segment - the visual-verification line (- [ ]/- [x] Visually verified in preview, - No visual surface (<reason>), or the stated-verification variant, shapes per the visual-verification skill where the repo has adopted it) - keep their mandated place in ## What & why and survive re-segmentation byte-identical, checked state included. Only the human who verified may flip the box either way; re-segmentation is not that human's proxy. The template ships exactly one unchecked item; if the source's attestation line is still unresolved, keep it unresolved - resolving it is the author's attestation, not Mode B's. A re-segmentation never resolves, duplicates, or deletes an attestation line, and where /visual-verification is adopted and the source has none, it adds the template's unchecked item - the one line Mode B may add: a convention line, not an invented fact (see /visual-verification).
3. Never invent facts while re-sorting. Re-segmenting reorganizes existing content; it adds nothing except the step 2 attestation item. The PR's own diff (gh pr diff --name-only, changed-file count) is source material, not invention - use it for the +N files: churn count and to confirm business-critical paths named in the body; prose facts still come only from the description.
4. A required Architecture bullet with no source content (business-critical files, tested flows, blast radius): write MISSING - author to fill under it. Surfacing the gap is the job; filling it belongs to the author. A source body with no coverage claims gets - Coverage ledger: none recorded in source - author to fill.