screenshot upload needs the PR number before the PR exists nf-r9fp ← Beads

Twinned from https://github.com/cfsh/ninefold/issues/408 by tools/beads/import_github.py's reconcile pass.

Filed unclaimed as a strategic uplift — not taking it. From the ninefold-c session (Row labels chunk); it cost a real extra commit on #406 today.

The paper cut

CLAUDE.md's visual-change rule says to commit shots to the orphan screenshots branch under pr<N>/, then link them from the PR body as blob URLs pinned to the screenshots commit. But the ordering is circular:

• pr<N>/ needs N, which only exists after gh pr create returns.
• The PR body needs the pinned blob URLs, which only exist after the screenshots commit is pushed.

So every visual PR either guesses N or does a two-step. On #406 I guessed pr405 (my previous PR was #404), another session opened #405 in between, and the fix was a second screenshots commit (git mv pr405 pr406) plus a body edit. Harmless, but it's a guaranteed-eventually failure that leaves a stale directory on the shared branch whenever the guess is wrong and nobody notices.

Worth noting the guess is *most* likely to be wrong exactly when the repo is busiest — several sessions opening PRs in the same minutes, which is the normal state now.

Options

• A. Document the two-step. Create the PR first with the body's screenshot section as a placeholder, upload under the real N, then gh pr edit --body-file. Zero tooling, one doc paragraph. It is what I ended up doing by accident.
• B. A tools/pr/shots.sh <pr> <files...> that does the checkout/copy/commit/push/return dance and prints the pinned markdown block ready to paste. Removes the sequencing question and the "which sha did I pin?" step, which is the other easy thing to get wrong.
• C. Name by branch, not number — screenshots/<branch-name>/. Known before the PR exists, and it survives a PR being closed and reopened as a fresh number (which #192 → #194 shows does happen). Costs the direct "which PR is this" readability of the current scheme.

A is nearly free and closes the correctness gap; B is the one that would actually save time on every visual PR; C is the only one that removes the ordering dependency entirely rather than sequencing around it. A+B compose.

Not urgent, and the existing rule works fine as long as whoever follows it knows to create the PR first — which is the part that isn't written down anywhere.