Design PR description for humans

Design PR description for humans: 30 seconds to “what, decided, looks like”

Gate this serves: 2026-10-08 Design-first feature gate. Noa’s merge of the design PR is the sign-off, so the PR body is the thing Noa actually reads before signing. Evidence it carries: 2026-10-08 Agent verification skills. The verification record lives below the fold in the body. This note decides what sits above it. Reviewer: 2026-10-08 PM worker reviewer agent orchestration. Freezy can only read GitHub/Origin, so every rule here ends in a check Freezy can run on the body text.

Pinned 2026-10-09 ~02:30 (UTC+8). Skill files were read from shallow clones at default-branch HEAD (gstack 8bb6d65, Every 67035e9, superpowers 8ca22db, Codewhale 9524531, mattpocock b0618bc, luoling8192 ae59b8b) or fetched raw (tldraw, deepseek-harness, aspire, cli/cli). Star counts come from the GitHub API at pin time. X dates are converted to UTC+8. Codex was not used.

TL;DR: the rules that matter

1. Bottom line first (BLUF). Line 1 is one sentence: what the feature is plus what is true after merge. A reader who stops there should still be right (Google CL: “the first line should stand alone”; tldraw “inverted pyramid”; Every “a reader can stop anywhere”).
2. The artifact is the second thing on the page, inline, under ## Outcome. CLI: a fenced console block with real $ command lines and their real output. GUI: one embedded image or a short video. A link to docs/design/…-artifact.md doesn’t count. Label where it came from (“prototype proto/x@sha, run 10-09” or “intended output: spec, not runnable yet”).
3. Decisions are ≤5 one-line bullets: “X over Y because Z”, each tagged you approved or proposed (merge = approve). Then ≤3 checkboxes under “Your call before merge”. Everything else is the design doc’s job.
4. Hard budget above the fold: ≤40 rendered lines and ≤1,200 characters of prose, not counting the artifact block (artifact ≤20 lines, or 1 image / 1 clip ≤30 s). Rationale, L/S tables, budget, full sessions and the verification record go in <details> or the design doc.
5. Never restate the diff or narrate the process. No file lists, no “I checked X then Y”, no emoji walls, no empty “N/A” sections. A length cap alone doesn’t fix slop (@satya164), so the fixed shape does the work.
6. Get media in with gh pr create|edit --body-file body.md --attach <file> (gh ≥ 2.99.0, 2026-09-01). It uploads to GitHub user-attachments, which inherit the repo’s visibility. Never host on a public repo, gist or gitshot: that is exactly the PixelLeak failure (13,000+ internal screenshots leaked).
7. Make it checkable. Freezy fails a PR whose ## Outcome section has no console block and no embedded image/video, or whose artifact is hidden inside <details>, or whose top section is over budget. A link alone fails.

---

1. Recommended design-PR body (copy-paste)

What it replaces: the current design-first-feature “Design PR body (human skim)” list (What, Artifact, Decided, Sign-off). The order stays the same. This version adds the budget, the provenance label, the fold and the check hooks. Worked example: greet --loud from nstack-lab.

**`nstack-demo greet --loud` prints the whole greeting in uppercase; plain `greet` is unchanged.** Merging this PR approves the design.

## Outcome
```console
$ nstack-demo greet noa --loud
HELLO, NOA
$ nstack-demo greet --loud
HELLO, WORLD
$ nstack-demo greet --lowd
usage: nstack-demo greet [name] [--loud]
$ echo $?
1
```
<sub>Source: intended output from design §2 (no code yet) · full session in the fold below</sub>

## Decided
- D1 Uppercase the whole line, not just the name: the flag means "loud greeting" (*you approved*)
- D2 `--loud` works before or after the name, hand-parsed, no new dependency (*you approved*)
- D4 An unknown `--flag` prints usage and exits 1 instead of becoming the name (*you approved*)
- P1 Casing lives in `greet(name, {loud})`; the CLI only parses (*proposed; merge = approve*)

## Your call before merge
- [ ] P1 OK? Reply "cut P1" to drop it
- [ ] Budget OK: ≤4 files · 0 new public symbols · 1 issue

Design: `docs/design/greet-loud.md` · Issue: none · Prototype: none · Merge = sign-off

<details><summary>Why this shape (3 alternatives)</summary>

(A) Uppercase in `cli.ts`: behavior escapes unit tests. (B) commander/yargs: a dependency for one boolean. (C) …. Full comparison: design §3.
</details>
<details><summary>Full CLI session (7 invocations, incl. error paths)</summary>…</details>
<details><summary>Layout, public surface, budget</summary>Design §4–5 (L1–L3, S-list, tolerance +25%).</details>
<details><summary>Glossary / ADR changes</summary>+2 terms in GLOSSARY.md; ADR candidates dropped: … (failed "hard to reverse").</details>

Rules for each block

• Lead line: ≤2 sentences, ≤300 chars. Outcome-shaped, not mechanism-shaped (Every: “If the lead describes what was edited rather than what is now different… rewrite it”). End with the sign-off sentence so Noa knows a merge is a decision.
• Outcome: one artifact, the happy path plus the most important error path.
  • CLI: use ```console with $ prompts so input and output can’t be confused. Show exit codes by printing $? or noting them in a trailing comment. PR #2 in nstack-lab used # stdout: comment lines instead; that reads fine, but it can’t be checked or re-run.
  • GUI: one image (or a before/after pair in a 2-column table for redesigns), or one clip of 30 s or less.
  • Always add the <sub>Source: line. Allowed provenance labels: prototype <branch>@<sha> run <date>, scaffold @<sha>, mock/wireframe, intended (spec).
• Decided: use the design doc’s own IDs (D-, P-) so Freezy can cross-check them (§5). Write “X over Y because Z” in ≤120 chars. Never mark the agent’s own picks you approved (design-first-feature HARD GATE).
• Your call: only decisions the merge itself will ratify, as checkboxes. This borrows Devin’s “Review & Testing Checklist for Human” idea and pr-with-evidence’s “Decisions only you can make”. If there are none, write “Nothing beyond merge.”
• Binding line: Design: <path> (the design PR has no merge SHA yet; Freezy records @<merge sha> after merge, per the gate digest).
• Fold: one <details> per question a reviewer might have. Never put the Outcome artifact inside <details>, because GitHub collapses it by default and nobody opens it.

---

2. Variant: implementation PRs and other review PRs

**Invoices can now be created from the API and listed in the dashboard.** Implements design D1–D4.

## Outcome  (captured at `abc1234` = PR head)
![Invoice list with two rows, one overdue](./artifacts/after.png)      ← gh --attach rewrites this path
(for a fix: a Before | After table; for CLI: a console block as above)

## Deviations from design
None. (or: A1 split `invoice.ts` into `types.ts` + `service.ts`: seed, no amendment needed.)

## Where to look
1. `src/billing/invoice/service.ts` `createInvoice`: the idempotency key path (riskiest)
2. migration `0007_invoices.sql`: one-way door

Design: docs/design/invoices.md@<merge sha> · Closes #12 · Verification: 14 checks PASS, 2 Not run (see fold)

<details><summary>Verification record @ abc1234</summary>(pr-with-evidence §3 record)</details>
<details><summary>Conformance self-report</summary>Paths ⊆ layout: yes · New public surface: S1–S3 only · Budget: files 6/8, LOC 210/300</details>
<details><summary>Change map / diagrams</summary>…</details>

	Design PR	Implementation / other review PR
Line 1	What the feature will do + “merge = approval”	What now works (or the symptom fixed)
Outcome artifact	Intended or prototype output; provenance label required	Real capture at the head SHA; fixes show Before/After from the same scenario (tldraw, deepseek)
Middle section	Decided (D/P lines) + Your call	Deviations from design (amendment or “None”) + Where to look (1–3 pointers, never a file list)
Verification record	Usually tiny (design self-check, check-design CI)	Required, in the fold, with its one-line headline (PASS/Not run counts) visible above the fold
Media in the repo	Design assets may be committed under docs/design/assets/<feature>/ because they are part of the signed design	Never commit PR-only captures; --attach them (pr-with-evidence, luoling8192, deepseek, aspire all agree)
Bugfix shape	n/a	tldraw: “This PR fixes a bug where ” → Before → After → test “fails on main and passes with this change”

Other review PRs (dependency bumps, refactors, docs): Every’s sizing table applies. “Small + simple: 1-2 sentences, no headers. Under ~300 characters.” There’s no Outcome section when nothing is observable, but say so in one line (“No behavior change: refactor of X; tests unchanged”).

---

3. Getting artifacts into the body as an agent

GitHub: what exists now

• gh --attach (default). gh v2.99.0 (release published 2026-09-02 04:25 UTC+8; changelog dated 09-01). The flag works on gh pr create|edit|comment and gh issue create|edit|comment.
  • “A local path already referenced in the body is rewritten in place, so ![alt](./login.png) keeps its alt text… Anything attached but never referenced is appended at the end” (changelog). For a video player, “The reference must be the only content in its paragraph” (docs).
  • Types: PNG, JPEG, GIF, WebP, SVG, MP4, MOV, WebM. “Size limits match the web upload flow: 10 MB for images and GIFs, 10 MB for video on Free plans, and 100 MB for video on paid plans” (changelog). At most 50 --attach values per invocation (cli/cli skills/gh).
  • Auth and hosts: needs write access and an OAuth token or PAT. “GitHub Enterprise Server and most GitHub App tokens are unsupported.” That matters if a worker pushes as a GitHub App rather than as a user.
  • Partial failure: “Uploads stop at the first failure. If earlier files uploaded, gh still writes those attachments and exits non-zero” (@AntonVlac 09-27: don’t report “no PR” from the exit code alone).
  • Privacy: GitHub docs say “For public repositories, uploaded files can be accessed without authentication… private… only people with access”. aspire’s skill adds: “the attachment API has no deletion endpoint”, so inspect every image for secrets before upload.
• Before gh 2.99 there was no sanctioned path. cli/cli discussion #4745 says “there isn’t a way to upload images from the CLI”. The web upload goes through /upload/policies/assets, which “rejects a PAT with 422” (pr-media). Ben Sheldon documented a token-accepting uploads.github.com/user-attachments/assets endpoint as “unofficial, undocumented”. I didn’t check whether gh uses it.
• PixelLeak is why the default matters. Glow Labs (2026-09-29; The Register) found “over 13,000 internal images… over 300 organizations”.
  • Agents that couldn’t attach created public repos, 93% of them under personal accounts. A third of affected orgs used gitshot, which is public by default.
  • At one vendor, “over a dozen agents had encoded this approach as a skill”.
  • The lab agent’s reasoning: “GitHub cannot render images from a private repo in a PR description — its image proxy fetches anonymously… so I created a new public repo”. Rule for nstack skills: an agent never creates repos, gists or releases to host evidence.

Fallbacks, in order

1. No upload: put text in the body. For CLI work this is the preferred form anyway: a console block renders everywhere (GitHub, Origin, email notifications), is searchable, and Freezy can parse it. Showboat (showboat exec demo.md bash "…" → showboat verify) produces exactly these blocks from real runs. Paste the exec blocks into Outcome and keep the .md in the fold or the design dir so CI can verify it (simonw/showboat, 1,232★, Apache-2.0, last push 2026-03-14).
2. Terminal motion (TUI, spinners, interactive prompts):
   • VHS .tape → Output demo.gif / .mp4 / .webm (charmbracelet/vhs, 21,071★; needs ttyd + ffmpeg). The tape is a reproducible script, so commit it, not the GIF.
   • Or asciinema rec → agg (1,730★, GPL-3.0) → GIF.
   • GitHub won’t run the asciinema player inline, so a .cast link is a link and fails the check. Attach the GIF with --attach and keep it under 10 MB (trim --fps/colors).
3. --attach can’t apply (GitHub App token, GHES, >10 MB):
   • Push to a same-repo orphan assets branch (deepseek-harness record-browser-gif: “a branch with no parent commit and nothing but media”, one per PR series), or use pr-media hidden-ref (refs/uploads/pr/<N>).
   • Embed https://github.com/<owner>/<repo>/blob/<sha>/<file>?raw=true. pr-media says these URLs inherit “the repo’s visibility”. The PixelLeak lab agent claimed anything committed to a private repo “shows up broken for reviewers”. Not verified either way. Test once on a private nstack repo before relying on it.
   • Release assets (Marek Šuppa, prerelease tag per PR) are the same trade-off.
4. Never:
   • external image hosts or new public repos for private work;
   • cookie-based uploaders such as drogers0/gh-image that reuse your browser’s GitHub session cookie. That is credential scraping, and a full-account bearer (pr-media: “hands out a bearer credential for your entire GitHub account”);
   • committing PR-only binaries to the feature branch.

Cursor cloud agents

• Capabilities: artifacts (screenshots, videos, logs) “are attached to the PR”. Embedding them in the GitHub PR description needs the opt-in “Allow posting artifacts to GitHub”, and then “artifacts in PR descriptions use long, unguessable URLs that are viewable without authentication”.
  • That is a weaker privacy model than --attach. Fine for public repos. For private repos it’s Noa’s call, since anyone holding the link can view it.
  • Lauren (@poteto), as quoted by @ChrisSimpson 09-16: cloud agents “can produce videos (and narrate if you tell them to) and attach them in the pull request description”.
• Observed in nstack-lab: Cursor wraps the agent’s text in <!-- CURSOR_AGENT_PR_BODY_BEGIN -->…END and appends “Open in Web/Cursor” badges. Freezy should parse only between the markers.

Origin (cursor.com/codebase)

• PR body is a plain string; “a body longer than 65,536 characters” is rejected (API). The Origin API index and the cursor-origin MCP have no attachment/upload endpoint.
• On 2026-08-24 Cursor staff confirmed “the Markdown preview in the Codebase tab on the web currently doesn’t render images, whether they use relative paths within the repo or full URLs” (forum). Whether PR descriptions render images or <details> is unverified. I didn’t create a test PR, since that would be a visible write.
• Origin default:
  • CLI: a console block (works today).
  • GUI: commit the capture under docs/design/assets/<feature>/ (design PRs only), embed it with a relative path and name the path in the <sub>Source: line, so a broken render still points somewhere.
  • For GUI-heavy implementation PRs, prefer a GitHub-mirrored repo, where --attach works.

Check a reviewer bot can run (body text only)

• R1 A ## Outcome heading exists within the first 15 non-blank lines (after stripping the Cursor markers and HTML comments).
• R2 The Outcome section, up to the next ## , contains at least one of:
  • (a) a fenced block tagged console|shell|sh|bash|text with ≥1 line starting $ and ≥1 line that doesn’t;
  • (b) ![…](https://github.com/user-attachments/assets/…) or <img src=…user-attachments…>;
  • (c) a bare https://github.com/user-attachments/assets/<uuid> on its own line (video);
  • (d) ![…](…) pointing at this repo (blob/<sha>/…?raw=true or relative docs/design/assets/…).
• R3 That artifact isn’t inside <details>.
• R4 A plain link ([x](…), a .cast/.md/.mp4 link mid-sentence) or a bare path with no embed → FAIL: link-only artifact.
• R5 Forbidden hosts: gist.github.com, raw.githubusercontent.com/<other owner>, github.com/<other owner>/…, /_gitshot, imgur, … → FAIL (advisory on public repos).
• R6 Characters before the first <details> (minus the Outcome block) ≤ 1,200.
• deepseek’s stronger version (render through GitHub’s Markdown API and confirm the <img>, then GET the asset for 200 + image/gif) needs execution or network, so it belongs to a CI job, not Freezy.

---

4. Existing skills and tools, ranked for this job

#	Skill / tool	What to take	Gaps
1	tldraw write-pr (SKILL.md; tldraw 50,818★)	“Default to short… If a reviewer would need their own AI to interpret yours, it has failed.” Inverted pyramid. “Never invent the why… ask the user”. Before/After recordings via a scripted Playwright scenario + gh pr edit --attach, “Under ten seconds each”, contact-sheet check. Preserves a human-written note “byte-for-byte”	Repo-specific bottom ceremony (Change type / Release notes / LOC table always). No decisions section
2	mattpocock pr (SKILL.md, 280,761★, MIT; Summary menu credited to Dex Horthy’s show-me)	Three sections only: Summary (smallest visual: call tree, diff-sketch, Mermaid), Evidence Before/After (“Screenshots are S-tier… Execution-based evidence is A-tier”), Merge Danger (one-/two-way door, blast radius). “Skip all preambles”	No upload mechanics, no length number, no decisions block. Evidence comes after Summary
3	Every ce-commit-push-pr → pr-description-writing.md (ref, 25,431★)	“Size by decision cost, not diff shape”. Sizing table (small: <300 chars; large: “~100 lines, cap ~150”). Outcome-not-mechanism rule with Bad/Good pairs. “Session-settled provenance” one-liner. Step E cut-audit. Runs prose through ce-noslop	Evidence goes last (“Place before the badge”). “CE has no capture workflow of its own”. 208-line reference
4	deepseek-harness record-browser-gif (SKILL.md, 245,625★)	Every GUI PR MUST embed a GIF from a real server. Records the demonstrated commit next to the GIF. Re-reads the PR head before and after attach. Orphan assets-branch fallback. “Never commit a GIF to the pull request’s own branch”	Heavy; tied to its own stack
5	luoling8192 create-pr-with-evidence (repo, 2★; Noa’s pinned upstream)	Visual workflow (merge-base worktree, identical viewport, reject bad captures), “Upload every local image as a GitHub user asset”, stop rule when upload is impossible	Body puts ## Visual changes near the bottom. No length budget. Upload step names a skill, not --attach
6	microsoft/aspire create-pr (SKILL.md)	Gate --attach on gh pr create --help advertising it; “do not… call GitHub’s undocumented attachment endpoint”. Secret/PII inspection before upload. “Do not leave the placeholder in the final body”	GUI only; asks the human to add screenshots when it can’t
7	Codewhale PR template + cw-handoff (41,082★)	“Short is good.” What and why / Issue / How I tested (“Commands you ran and what they showed… For visible UI changes, add a screenshot or recording”). cw-handoff: keep done / suspected / blocked separate	No artifact placement rule; cw-land is about merging, not the body
8	gstack /ship pr-body.md (135,606★)	Plan: <path> binding. gstack-post scans the exact body bytes for secrets/PII before posting	14 fixed sections (Test Coverage, Pre-Landing Review, Exploratory QA, Design Review, Eval Results, Greptile…) plus ”🤖 Generated with Claude Code”: the opposite of skimmable. Useful only as the fold
9	superpowers finishing-a-development-branch (296,498★)	Defers to “the repo’s PR template and conventions”	No body guidance at all
10	Vendor defaults	Devin: devin_pr_template.md override; default is “a single Summary section… for a reader who hasn’t seen the diff” (docs). Copilot: “will keep the title and body up to date” as it pushes (docs). Cursor: markers + optional public-URL artifacts. Codex cloud: Summary + Testing, with citations kept “not the body of the PR message” (from a leaked 2025 prompt; unverified against the current product)	None of them puts an artifact first by default

Also relevant:

• Conventional Comments (spec): praise|nitpick|suggestion|issue|todo|question… + (blocking). It’s for Freezy’s comments, not the body.
• Google eng-practices CL descriptions: “Complete sentence, written as though it was an order”; “the first line should stand alone”.
• GitHub helping others review: state purpose, give an overview, and say what kind of feedback you need (paraphrased).
• Upload helpers: pr-media (6★, browser/hidden-ref/release strategies, keeps the session in the browser), atani/gh-attach (21★) and Addono/gh-attach (3★) (browser-session based; details not re-checked), Kery (25★, posts a video comment; not read). All are superseded by --attach for the common case.
• No skill found ships a numeric above-the-fold budget, and none ships a body-shape check a reviewer bot runs. Both are new here.

---

5. Anti-patterns, with field quotes

• Essay instead of decision. “Please, stop pasting AI generated essays into PR descriptions 😫 Just write two simple bullet points so we can review the code and move on.” (@romxdev 09-12, 135 likes).
  • “An essay and an MD table for a few file changes. Just give me a couple of bullet points and the ticket ref.” (@GilCompiles 04-12)
  • Warp’s Zach Lloyd: “our agents are creating overly verbose PR descriptions”, so he made the verbosity scorer stricter (08-22).
• What without why. “LLM writes a wall of text about what the PR does and misses the why” (@bmacabeus 02-06).
  • “LLMs really want to summarize, and that’s not what I want from a good PR description” (@joelquen 07-12).
  • Counter-signal: “handwriting digestible PR descriptions with screenshots that explain the why, not what or how” (@raunofreiberg 07-07, 396 likes).
• False authority and invented facts. “AI slop PR descriptions just give a false sense of authority to content that isn’t real” (@RhysSullivan 2025-10-30).
  • A maintainer rejected a PR because “The very first line of PR description states an incorrect fact” (@kekekeks 03-20).
  • “too verbose and often stale or plain wrong” (@_Felipe 03-23).
  • Fix: tldraw’s “never invent the why”, plus provenance labels on artifacts.
• Polish as review theater. “The PR description is beautifully written… The reviewer skims it, sees green CI, and clicks approve in 8 seconds. The actual diff is 1,400 lines across 23 files” (@dash_tech_guy 05-29). Fix: “Where to look” and “Deviations” must name the risky part, not reassure.
• File-by-file changelog. Every: “Bad (lists what was edited)…”. tldraw: “No file-by-file walkthrough” and no “inventory of every changed file”. The Files tab already shows this. Corollary from Help Wanted: “A parser, a test, or a CLI flag does not need a PNG”, so write n/a — no UI rather than inventing a screenshot.
• Process narrative. nstack-lab design PR #1 opened with “This is the design-first gate…” and “Checked against the current tree: …”, with no artifact and no statement of the feature’s behavior. PR #2 led with the CLI artifact and was much easier to read (both read 10-09 via cursor-origin).
• Ceremony sections, emoji, badges. gstack’s 14 sections. An AIDev-based study (arXiv 2602.17084, 33,596 PRs) found Claude Code descriptions have “a significantly high volume of text” and emoji. Codex was “the only agent that frequently utilizes headers and lists”, with the highest merge rate (82.6%). The authors stress this is non-causal.
• Video as a substitute for text. “tried loom links in PR descriptions for a month… you can’t skim a video, so people don’t” (@bygregorr 09-02). Video supports line 1; it never replaces it.
• Length gates alone. A >1,000-character Action “leaves a comment asking to shorten it… Do I get better descriptions? No.” (@satya164 09-20). The budget has to come with a fixed shape.
• Leaking evidence. PixelLeak (§3). One vendor’s agents “encoded this approach as a skill”. Skills spread bad hosting habits fast.
• Reddit was thin. The only on-topic thread found (via reddit.sentinel-team.org snapshot; subreddit not shown; original not opened) has: “I expect you (the person who generated it) to read over it, summarize and shorten it”.

---

6. Turning this into nstack (proposal; no skill files were edited)

Status. design-first-feature and pr-with-evidence exist in two identical copies:

• the vault’s nstack skills folder;
• the skill library.

They are mapped in nstack’s STACK.md (seats 1b and 5). The upstream checkout’s design-first-feature/SKILL.md is an older copy without the “Design PR body (human skim)” section. The local nstack-lab clone holds only greet-loud.md (the design draft). The real repo is Noa’s private sandbox repo, with design PRs #1 and #2 open.

Shape. Don’t add a seat. Add one shared reference, nstack/_shared/pr-body.md, and point both skills at it.

1. pr-body.md (shared):
   • the §1 and §2 templates;
   • the budget (≤40 rendered lines above the fold; ≤1,200 chars of prose; lead ≤300 chars; Decided ≤5 × 120 chars; Your call ≤3);
   • provenance labels;
   • the anti-pattern list from §5 as a self-check;
   • “write the body to body.md, then gh pr create --body-file body.md --attach …”;
   • “on Origin, artifact = console block or committed design asset”;
   • the hosting never list (repos, gists, releases you create, gitshot, cookie tools).
2. design-first-feature edits:
   • replace §“Design PR body (human skim)” with a pointer plus the R1–R6 self-check;
   • in §5b, require Showboat exec (or a VHS tape) when a prototype or scaffold can run, so CLI output is captured, not hand-typed;
   • otherwise label it intended (spec).
3. pr-with-evidence edits:
   • in §5 Compose, put ## Outcome right after Summary and move Change map / Architecture / Boundaries / Verification record / Conformance into <details>, keeping one visible headline line (“Verification: N PASS, M Not run @ sha”);
   • in §4 step 5, replace “Upload images as GitHub user assets” with the concrete --attach command, its requirements (gh ≥2.99.0, user token not App token, ≤10 MB) and the fallback order from §3;
   • resolve the conflict: “Never commit PR-only images” stays for implementation PRs, and design assets under docs/design/assets/ are exempt (they’re part of the signed record).
4. auto-reviewer (Freezy) addition: a “PR body shape” block. It is blocking for design PRs (the artifact is a HARD GATE there) and advisory for implementation PRs unless B- scenarios need visual evidence.

Freezy checklist (GitHub/Origin reads only)

## PR body shape (Freezy, at head <sha>)  — body from get_pull_request / pull_request_read, text between Cursor markers
- [ ] B1 Lead: first non-blank line ≤300 chars, not a heading, no "This PR"/"I " process opener
- [ ] B2 `## Outcome` within first 15 lines; artifact per R2; not inside <details>; link-only → FAIL
- [ ] B3 Provenance: `Source:` line present (design) / "captured at <sha>" == head (impl)
- [ ] B4 Budget: prose chars before first <details> (minus Outcome block) ≤1,200; Decided ≤5; Your call ≤3
- [ ] B5 Decided IDs exist in design doc §3 at head (get_file_contents ref=head); "you approved" only on D-lines tagged user-approved there
- [ ] B6 Binding: `Design: <path>` (design PR) / `Design: <path>@<sha>` + Closes/Related (impl)
- [ ] B7 Hosts: no gist / other-owner repo / _gitshot / external image host
- [ ] B8 No leftovers: no `TBD`, `<!-- Add …-->`, empty headings, "N/A" sections
Verdict: PASS / FAIL (<items>) / INCONCLUSIVE (Origin render unknown, image not fetchable)

What Freezy can’t verify:

• whether the image shows what the text claims (Noa’s eyes; the auto-reviewer checklist already has “Artifacts open and show the claimed state”);
• whether console output is real (only showboat verify in CI, read as a check run, proves that);
• whether a user-attachments URL came from this repo;
• how Origin renders images and <details>.

Cheap mechanical helper. A pr-body-lint CI job (GitHub Action, or an Origin check run, whose output.summary accepts Markdown up to 65,535 bytes) runs B1–B8 plus deepseek’s render check. Freezy then reads one check run instead of re-deriving it. This is the same pattern as check-design in the gate digest.

---

7. Not verified / gaps

• Whether blob/<sha>/x.png?raw=true renders in a private repo PR body for logged-in reviewers (pr-media says yes; the PixelLeak agent said no).
• Origin PR-description rendering of images, video and <details>.
• The exact endpoint gh --attach calls.
• Codex cloud’s current PR body format (only a leaked 2025 prompt).
• Copilot’s default body sections.
• Kery internals.
• Any primary Linear or Vercel PR-description guide (none found; Graphite’s guides are generic).
• Reddit originals.
• HN had no substantive thread on PR-description length; the comment API search errored.
• The @satya164 post is truncated in the X API, so I quoted only the visible text. The @ChrisSimpson post text names the livestream oddly; I quoted only Lauren’s claim.

---

8. Sources

• GitHub: gh v2.99.0 release · changelog 2026-09-01 · Attaching files with GitHub CLI · Attaching files · PR templates · Helping others review · cli/cli skills/gh · discussion #4745 · How to write the perfect pull request
• Writing guides: Google CL descriptions · Graphite PR description best practices · Help Wanted: PR descriptions maintainers read · Conventional Comments
• Skills: tldraw write-pr · mattpocock pr · Every pr-description-writing · deepseek record-browser-gif · luoling8192 create-pr-with-evidence · aspire create-pr · gstack ship pr-body · superpowers finishing-a-development-branch · Codewhale PR template · cw-handoff
• Artifact tools: Showboat · VHS · agg · pr-media · atani/gh-attach · Addono/gh-attach · gh-image (avoid) · Ben Sheldon on the upload endpoint · Marek Šuppa: release assets
• PixelLeak: Glow Labs · The Register · The Hacker News
• Vendors: Cursor cloud agent capabilities · Origin pull requests · Origin create PR API · Origin images forum bug · Devin PR templates · Copilot coding agent best practices
• Research: How AI Coding Agents Communicate (arXiv 2602.17084) · AIDev (arXiv 2602.09185)
• X: links inline in §3 and §5. Origin: Noa’s private sandbox repo, PRs #1 and #2 (read through cursor-origin).
• Vault: 2026-10-08 Design-first feature gate · 2026-10-08 Agent verification skills · 2026-10-08 PM worker reviewer agent orchestration · 2026-10-08 Agent skills for splitting work into issues · 2026-10-02 Agent screenshot and UI expression · nstack’s STACK.md