Files
gstack/ship/sections/capy-pr.md
T
Garry Tanandcapy-ai[bot] c53b15c48d Open pull requests with three plain lines and land each one as a single commit (GST-2737) (#4438)
* WIP plain PR bodies and squash messages

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Fold PR bodies to three plain lines and land every PR as one plainly titled commit

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Expect the plain commit body in the train land tests

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Count the new policy keys in the floor tests and record the ship size change

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Let older, generated and Dependabot PRs pass the body check, and keep comments posting

The opening check now follows the same date and branch exemption as the rest of the body check, Dependabot branches are exempt, the exemption only counts for branches in this repository, a merge that cannot read the PR waits instead of refusing, and a broken policy file no longer stops comments.

Review-Finding: p1/specialist-batched#1 reader=testing
Review-Finding: p1/specialist-batched#2 reader=testing
Review-Finding: p1/red-team#1 reader=red-team
Review-Finding: p1/red-team#2 reader=red-team
Review-Finding: p1/red-team#4 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Stop re-posted PR bodies from duplicating sections, and let file names through the word check

Posting an already-folded body now replaces each section once instead of keeping the old copy beside it, and listed words inside file paths or file names, such as a test file in the Tests section, no longer count as prose.

Review-Finding: v2/outside-voice#3 reader=outside-voice
Review-Finding: v2/adversarial-native#2 reader=adversarial-native
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Describe the folded three-line PR body in the skills guide and the prose lint help

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-17 13:14:33 +00:00

4.5 KiB

Step 19-C: Capy PR body (What changed, Why, Blast radius, Approvals)

Read only when Step 19 printed CAPY_PR: on. Under Capy a person decides the merge from the PR and the READY report, through a Captain, so the body shows what changed in pictures, why, and who approved what. Guide: captain.md beside the Capy gstack skill's SKILL.md.

Order. The plain opening lines come first (at most three), then ## What changed, ## Why and ## Blast radius, then the standard sections. ## What changed holds the pictures below, then the template's themes, without repeating the captions. gstack-post folds each into a collapsed section. ## Approvals goes inside the closing Agent notes section, where gstack-ship-receipt write also puts the receipt. A body posted any other way, Capy's PR tool included, is folded first: pass the output of ~/.claude/skills/gstack/bin/gstack-post fold --body-file "$PR_BODY_FILE" (it posts nothing, and exit 4 with PLAIN_BODY: lines means rewrite the body file first).

  1. Pick the evidence: one to three before/after pairs, highest-signal first. The first is the key image.
    • UI change: screenshot the changed screen at the base and on this branch with the browse flow, or your host's browser, at the same size.
    • Skill or prompt change: ~/.claude/skills/gstack/bin/gstack-pr-shots --path <template or SKILL.md> --heading "<changed section>" --caption "<what changed and why>".
    • CLI change: save the output of a command this ship already runs, at the base and on this branch, to files inside the repository (.gstack/tmp/before.txt, .gstack/tmp/after.txt), then ~/.claude/skills/gstack/bin/gstack-pr-shots --before <file> --after <file> --kind terminal --caption "<…>". Never run a command with side effects just to make a picture.
    • No visible surface: picture the source section or test output that best shows the change. gstack-pr-shots refuses inputs that match the secret scanner (PR_SHOTS_INPUT_REFUSED). Remove the secret from the capture; never work around the refusal.
  2. Read SHOT_PNG:. A path: use it. unavailable (…): screenshot the printed shot.html with your own browser at 880 px wide and use that PNG. failed (…): use the text version only.
  3. Upload. Only for a public repository (gh repo view --json visibility -q .visibility prints PUBLIC). A private repository gets the text version, unless the person approved images for it (record that with gstack-approvals add). Upload each PNG with Capy's PR asset tool (tools.pr.uploadAsset). Embed exactly the URL it returns, with the caption as alt text: ![<caption>](<url>) (a returned bare video URL stays on its own line). If an upload fails, retry once, and only for a transient error. Otherwise use the text version and write image upload failed: <reason> under the caption. Never block publication on an image.
  4. Under every image: a one-line caption saying what changed and why, then the contents of the printed text.md (a collapsed text before/after, for readers who cannot see the image and for search).
  5. ## Why: two or three sentences. The first states the problem in the person's words (the issue, the failed run, or their request, quoted); the rest say what changes for them. No inventory: BAD "Adds a lint and a CI step." GOOD "'The review loop is too overzealous.' Pass 2 now reads only pass 1's range."
  6. ## Blast radius: the body template's item, written once, here: what else the change touches and the one fact that makes that safe, with the evidence-ladder rung it reached (file:line read, walked failure path, script ran, repro).
  7. ## Approvals (inside Agent notes): the output of ~/.claude/skills/gstack/bin/gstack-approvals render --plan "<the brief's Plan line>", verbatim. It escapes its cells, and the receipt never reads it as an approval citation. A public repo (or unknown visibility) gets only Approved: yes|no (record <id>) and Plan: approved (record r-<id>); never pass --full for a PR body. If render refuses with a PLAN_* code, it printed nothing: run the fix it names and render again. On APPROVAL_RECORD_UNAVAILABLE keep its text and say so in the READY report. Never type rows by hand.
  8. READY report: attach the key image's PNG to the report you send (Capy's message attachments) and give its uploaded URL, so the Captain can show it inline.