Phoenix PR Description

A PR body lets a reviewer answer three questions at a glance: do I need to review this, how long will review and testing take, and should I hand it to my agent. Write only what serves those three. The author can always extend the body; a body nobody reads cannot be shortened after the fact.

Default to short. A one-line What plus the provenance table is a complete body. Add a section only when a reviewer needs it to answer one of the three questions.

Template

Use these H2 headings in this order. Omit a heading when it would be empty. Never add others.

resolves #<issue>            <- only when an issue exists

## What
<one sentence: the change, ticket, dependency such as "Stacked on #16660">
<media: one video or screenshot; required when the PR changes rendered UI>
<optional: up to 4 bullets, one sentence each, behavior not files>

## Try it                    <- only when a reviewer can exercise the change in under a minute
1. <step ending in what the reviewer should observe>

## How this PR was made
| Agent | User turns | Steering turns | Questions asked | Sessions |
|---|---|---|---|---|
| <tool (model)> | n | n | n | n |

**Starting point:** <the ask in a few words>; <bare / with constraints / with spec>
**Steering:** <categories only, from: scope, approach, correctness, style> or none
**Abandoned:** <approach, reason> or none
**Verified:** <what ran>. Not verified: <gap> or none
**Look hardest at:** <riskiest hunks>

<sub>Stats as of <short sha>, counted from <method>.</sub>

Limits, all hard:

• What: one sentence, then at most 4 bullets of one sentence each. No Why section; fold the reason into the sentence only when it is not obvious from the ticket.
• Bold only on-screen control names. Code font for identifiers. No nested bullets, no file lists, no "Summary" or "Changes" headings, no closing paragraph.
• Each provenance line is one line of at most 12 words. Steering names categories, not details.
• Media: one item, bold caption above it stating what to notice. Required when the PR changes what a user sees (components, styles, layout, motion); capture it with the phoenix-pr-screenshot skill. When it cannot be captured, say why in What instead.
• Total body above the provenance section fits on one screen without scrolling.

Reference: Arize-ai/phoenix#16662 is the upper bound for a large change. Most PRs should be far shorter. See examples.md for a large, a small, and a non-UI body.

Provenance definitions

Describe the work, not the person. Paraphrase the ask; never quote it. Write "none" rather than omitting a line. Never grade the PR ("low risk", "thorough"). A one-prompt, zero-steering PR is a normal outcome and is reported as such.

Counting

Count from a record, not memory. One method is given; invent the equivalent for your own tool.

Claude Code writes each session to ~/.claude/projects/<slug>/<session>.jsonl, where the slug is the working directory with / replaced by -. Human messages are user entries whose message.content is a string:

f=$(ls -t ~/.claude/projects/$(pwd | sed 's#/#-#g')/*.jsonl | head -1)
jq -r 'select(.type=="user" and (.message.content|type)=="string") | .message.content' "$f"

Pipe through wc -l for user turns; read the lines to classify steering. Sum across files when several sessions contributed. With no record, or after a compaction, write approx. after each number and name the method in the stamp as "recall".

Keeping it current

Every edit to the body, including after review rounds, recounts the table and rewrites the stamp with the commit the stats cover. Reviewer-driven turns are user turns and usually steering turns.

Before posting

• Body above the provenance section fits on one screen
• What is one sentence plus at most 4 one-sentence bullets
• A UI change carries media, or What says why it has none
• Every provenance line is present, one line, 12 words or fewer
• Counts came from a record, or every number carries approx.
• Stamp names the current head commit