The AI Pull Request Body: h5i's Review Surface for Agent Work

A growing share of the branches a reviewer is handed today were written by an agent — and so was the PR description explaining them. That is the trap. When the same system authors the code and the summary, the summary is a self-report: a confident paragraph the model wrote about its own work, with no obligation to mention the test it skipped, the file it edited without reading, or the credential it pasted into a config. Reviewers know not to trust an author's self-assessment from humans; an LLM's prose is no more load-bearing, just more fluent.

You already know the standard moves here: write the PR body by hand, or let an AI summary bot read the diff and paraphrase it. The first is honest but expensive and rarely done well on agent branches; the second scales but only ever sees the result — the diff — never the process that produced it. The option you may not have considered is to generate the review body from captured provenance: the prompts, model and agent identity, test metrics, audit findings, and reasoning recorded as the work happened. The reviewer then reads evidence the author could not have quietly omitted, in the place review already happens.

That is what h5i share pr post does. It renders h5i's shared context DAG, commit provenance, audit findings, and branch-scoped agent messages into a sticky GitHub comment. Re-run it and h5i updates the same comment instead of spraying duplicates across the thread. Its sibling, h5i share pr body, prints the same markdown to stdout so CI can own the PR description directly.

What the PR body answers

The packet is organized around the questions a reviewer actually asks before approving an agent's branch. Each answer is rendered from a recorded signal, not generated prose — a section self-omits when its signal is missing rather than inventing a plausible-sounding filler.

Post or preview

The common loop is: render locally with --dry-run to check the body, then drop the flag to upsert it onto the open PR. h5i share pr body takes the same style and limit flags but never touches gh — it is the CI path.

$ h5i share pr post --style review --dry-run
# render the reviewer brief locally; no gh call

$ h5i share pr post --style review
# upsert the sticky comment on this branch's open PR
✔ Posted h5i comment on h5i-dev/h5i#418

$ h5i share pr post --style review
# re-run after more commits: same comment, edited in place
✔ Updated h5i comment on h5i-dev/h5i#418 (id 2391847706)

$ h5i share pr body --style replay --limit 50 | gh pr edit --body-file -
# CI path: write the rendered markdown straight into the PR description

--limit caps how many commits feed the packet (default 25); --number pins a PR explicitly instead of auto-detecting from the branch. Both post and body share the style, limit, and coordination flags.

Five styles, one record

Style changes only the hero block at the top of the comment — the first viewport a reviewer or a screenshot captures. The audit sections, reasoning DAG, coordination threads, and per-commit provenance below the fold are identical across styles, because they all read from the same recorded evidence. Pick the framing that fits the moment; the facts do not move.

What is in the packet

Below the hero, every body renders the same ordered sections, each of which omits itself when it has nothing to say:

• 🔒 Credential-leak alert. If the audit found a secret on an added line, it is promoted above the hero as a rotate-before-merge banner — the leak is flagged, never reprinted.
• 🔁 Duplicate-code alert. Copy-paste the agent introduced, with the rule, file, and line that tripped it.
• 🧠 Reasoning DAG. The OBSERVE/THINK/ACT trace, collapsible below the fold (and expanded in-hero for replay).
• 💬 Agent coordination. Branch-scoped i5h message threads — review requests, risk callouts, handoffs — so a reviewer sees what the agents told each other. Off with --no-msg.
• 📜 Per-commit provenance. One row per AI commit: model, agent, prompt, token count, and test result, collapsed automatically past five commits.

The coordination section is deliberately conservative about what it republishes. By default it excerpts only review-typed messages (review request, risk, handoff, ask, and their typed replies); casual FYI and free-text chatter stay metadata-only unless you pass --msg-bodies, and --msg-limit caps how many threads render. Pulled message fields are untrusted input, so an unrecognized message kind is sanitized and escaped before it reaches the comment — a hostile kind can not break out of its rendered cell. This is the same terminal-injection defense the messaging layer applies everywhere it shows pulled text.

The sticky comment, not comment spam

CI that posts a fresh comment on every push turns a PR thread into a changelog nobody reads. h5i avoids this with a hidden marker. Every comment it writes begins with <!-- h5i:pr-comment v1 -->. On each run, pr post lists the PR's comments, finds the one starting with that marker, and edits it in place via gh api … -X PATCH; only if none exists does it post a new one with gh pr comment. The result is exactly one h5i comment per branch that tracks the latest state of the work — your re-runs update history rather than burying it.

How this compares

The PR comment is one rendering of a durable record, not the record itself. h5i keeps the truth in Git sidecar refs (refs/h5i/context, refs/h5i/notes, refs/h5i/memory), and the same evidence also renders as a terminal prelude, a local dashboard, or a compliance report. So the fair question is not "is a generated comment nice" but "what does this rendering let a reviewer see that the alternatives do not."

Reviewer workflow

A useful AI PR body should change review order. With --style review, start at the merge-status line and the focus files h5i ranks highest, read the evidence line and checklist, skim the reasoning highlights, then compare tests against the behavior that changed. The comment never replaces the diff; it tells you where the diff is most likely to hide a mistake.

This matters most on large generated patches. Without provenance, a reviewer spends equal attention on formatting churn and on security-sensitive changes. With it, blind edits, uncertainty notes, skipped tests, generated configuration, and high-churn files move to the top of the queue — and the routine churn drops to the bottom where it belongs.

The same record helps after merge. If a production issue surfaces later, the sticky comment is a compact account of the original task, the evidence available at review time, and the assumptions that were accepted. That is incident context, not just a tidier PR.

Requirements and failure modes

h5i share pr post needs the GitHub CLI installed and authenticated. It fails fast and explains itself when:

• gh is missing or not authed — it can not resolve the repo; run gh auth login and check gh auth status.
• No open PR for the branch — auto-detection has nothing to target; push the branch and open a PR, or pass --number N.
• You want a preview, not a post — use --dry-run, or h5i share pr body to print markdown for your own workflow.

The richest packets come from branches that used h5i throughout: a context goal and traces from the session hooks, h5i capture commit --tests for provenance and metrics, and h5i audit review before requesting review (Codex branches wire the same via h5i hook codex prelude and h5i hook codex sync). A branch that skipped all of that still renders — just with less to show. For the risk model behind the audit signals, see the AI-generated code audit framework.

Frequently asked questions

Conclusion

The reason to generate the PR body instead of writing it is not convenience. It is that an agent's own summary and a diff-only bot share the same blind spot: neither can show you what was left out. A skipped test, a file edited without being read, a secret pasted into a config, a rejected alternative — these live in the process, not the patch. h5i captures the process as it happens and renders it where review already occurs, sticky and redacted, with the audit signals that did not make it into the diff promoted to the top.

The packet does not ask you to trust the agent. It gives you the evidence to decide, lets you disagree with every line of it, and — because it is one rendering of a durable record — leaves the same facts available later as the dashboard, the compliance export, or the post-incident account. The PR comment is just the view the reviewer happened to need first.