docs(agents): mark a PR ready after the update that finishes it, and measure every area a change touches #1715

Merged
HumanBean merged 1 commit from HumanBean/Longshot:docs/ready-after-update into main 2026-11-19 06:36:01 +00:00
Owner

Type: docs · Risk: low · Tested on: n/a (docs only) · Needs: none

TL;DR

Agents are told to mark a pull request ready once it is ready, but only at the moment it first gets there. A PR often becomes ready later, through its last measurement, fix-up or test run, and then sits in work in progress where nobody reviews it. This PR tells agents to check again after each update and mark it ready then. It also says a PR's measurements must cover every area the change touches: the game for a change the game runs, the build's time and size for a build change, load time for a cache change, and several when one change touches several.

Breakdown

  • Who it helps: reviewers and authors waiting on finished PRs left in WIP, and players hit by a cost nobody measured (a slower build, a longer load).
  • What was wrong: the guide didn't say to check readiness again after each update, and didn't say to measure the areas a change affects beyond the one it targets.
  • What changes: the update step now ends with a check for readiness and pr ready; Complete the applicable evidence gains a bullet listing which numbers each kind of effect needs.
  • What does not change: the game, the build and every other rule; nothing.
  • How it was checked: read the rendered paragraph; docs only.
  • What is still open: nothing.
  • Risk: low: a sentence in an agent guide.

Why

Finished PRs get left in WIP when the update that finished them (a last measurement, a fix-up, a run) is not followed by pr ready. The guide said to mark a PR ready once it is ready, but put that before the update step, so an agent updating a PR had nothing reminding it to check again.

PRs also measure only the area they aim at: a compiler flag measured in fps but not in build time, a cache change measured warm but not on first run. CONTRIBUTING.md's Measurements table lists what counts per change type, but not that one change can need several kinds of numbers.

What changed

Two additions to the agents' PR guide:

  • docs: docs/agent-pull-requests.md, Open and update, the pr update bullet: after each push, measurement or test run, check again whether the PR is ready and run pr ready <n> then.
  • docs: docs/agent-pull-requests.md, Complete the applicable evidence: a new bullet, "Measure every area the change touches": game (fps, 1% low, frame time), build (time and size), loading and caches (load time, cache size, cold and warm), memory (RAM, VRAM), launcher, tools and scripts; an area that plainly can't be affected gets a line saying so.

The same notes go into Tooling's AGENTS.md in a companion PR (Tooling #22).

Measurements

Verdict: nothing to measure: a docs-only change.

Flags and settings

None

Testing

Tested: read the changed paragraph on the branch; docs only, nothing the game runs.

Not tested: tests/run_all.py was not run on this PC (the CI runs it); a docs line in a file no check reads by text.

Must be tested:

  • None

Risks

What could break: nothing the game runs.

Turning it off: revert the commit.

Compatibility: Nothing changes

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what
    can't be run by hand is in Testing's Not testable by hand, with why.
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and
    in Risks.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). Not run on this PC; the CI runs it.
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** docs · **Risk:** low · **Tested on:** n/a (docs only) · **Needs:** none ## TL;DR Agents are told to mark a pull request ready once it is ready, but only at the moment it first gets there. A PR often becomes ready later, through its last measurement, fix-up or test run, and then sits in work in progress where nobody reviews it. This PR tells agents to check again after each update and mark it ready then. It also says a PR's measurements must cover every area the change touches: the game for a change the game runs, the build's time and size for a build change, load time for a cache change, and several when one change touches several. ## Breakdown - **Who it helps:** reviewers and authors waiting on finished PRs left in WIP, and players hit by a cost nobody measured (a slower build, a longer load). - **What was wrong:** the guide didn't say to check readiness again after each update, and didn't say to measure the areas a change affects beyond the one it targets. - **What changes:** the update step now ends with a check for readiness and `pr ready`; *Complete the applicable evidence* gains a bullet listing which numbers each kind of effect needs. - **What does not change:** the game, the build and every other rule; nothing. - **How it was checked:** read the rendered paragraph; docs only. - **What is still open:** nothing. - **Risk:** low: a sentence in an agent guide. ## Why Finished PRs get left in WIP when the update that finished them (a last measurement, a fix-up, a run) is not followed by `pr ready`. The guide said to mark a PR ready once it is ready, but put that before the update step, so an agent updating a PR had nothing reminding it to check again. PRs also measure only the area they aim at: a compiler flag measured in fps but not in build time, a cache change measured warm but not on first run. CONTRIBUTING.md's Measurements table lists what counts per change type, but not that one change can need several kinds of numbers. ## What changed Two additions to the agents' PR guide: - docs: `docs/agent-pull-requests.md`, *Open and update*, the `pr update` bullet: after each push, measurement or test run, check again whether the PR is ready and run `pr ready <n>` then. - docs: `docs/agent-pull-requests.md`, *Complete the applicable evidence*: a new bullet, "Measure every area the change touches": game (fps, 1% low, frame time), build (time and size), loading and caches (load time, cache size, cold and warm), memory (RAM, VRAM), launcher, tools and scripts; an area that plainly can't be affected gets a line saying so. The same notes go into Tooling's `AGENTS.md` in a companion PR ([Tooling #22](https://git.magicbean.dev/MagicBeanDev/Tooling/pulls/22)). ## Measurements **Verdict:** nothing to measure: a docs-only change. ### Flags and settings None ## Testing **Tested:** read the changed paragraph on the branch; docs only, nothing the game runs. **Not tested:** `tests/run_all.py` was not run on this PC (the CI runs it); a docs line in a file no check reads by text. **Must be tested:** - None ## Risks **What could break:** nothing the game runs. **Turning it off:** revert the commit. **Compatibility:** Nothing changes ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what can't be run by hand is in Testing's Not testable by hand, with why. - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and in Risks. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). Not run on this PC; the CI runs it. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Member

Possibly related, for context:

  • PR #891 WIP: docs(agents): a review checklist, and the review skill moves to Tooling — Open agents/review guidance also edits agent workflows; inspect for any overlap in docs.
  • PR #818 docs(agents): disclose setup and pull request guidance — Merged PR introduced the guide being amended; context for this readiness guidance.
  • PR #1634 docs(contributing): a PR's switch carries its recommended value from the first push; measurements gate leaving WIP — Merged PR also updates the same agent PR guide, but covers switch/measurement rules.
Possibly related, for context: - PR #891 WIP: docs(agents): a review checklist, and the review skill moves to Tooling — Open agents/review guidance also edits agent workflows; inspect for any overlap in docs. - PR #818 docs(agents): disclose setup and pull request guidance — Merged PR introduced the guide being amended; context for this readiness guidance. - PR #1634 docs(contributing): a PR's switch carries its recommended value from the first push; measurements gate leaving WIP — Merged PR also updates the same agent PR guide, but covers switch/measurement rules.
HumanBean force-pushed docs/ready-after-update from 74772318fc
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 11s
PR description / Description follows the template (pull_request_target) Successful in 12s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 14s
Third-party parts / As their notes say (pull_request) Successful in 16s
Website / Website on Cloudflare (pull_request_target) Has been skipped
to ff4dd3a5a2
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 7s
CI / Workflow lint (actionlint) (pull_request) Successful in 11s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 11s
Third-party parts / As their notes say (pull_request) Successful in 12s
PR description / Description follows the template (pull_request_target) Failing after 4s
2026-11-19 06:29:01 +00:00
Compare
HumanBean changed title from WIP: docs(agents): check again whether a PR is ready after each update to WIP: docs(agents): mark a PR ready after the update that finishes it, and measure every area a change touches 2026-11-19 06:29:24 +00:00
Author
Owner

Added a second note in the same commit: measure every area a change touches (game, build time and size, loading and caches, memory, the launcher and tools), not only the one it targets.

Added a second note in the same commit: measure every area a change touches (game, build time and size, loading and caches, memory, the launcher and tools), not only the one it targets.
HumanBean changed title from WIP: docs(agents): mark a PR ready after the update that finishes it, and measure every area a change touches to docs(agents): mark a PR ready after the update that finishes it, and measure every area a change touches 2026-11-19 06:35:56 +00:00
HumanBean deleted branch docs/ready-after-update 2026-11-19 06:36:01 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1715
No description provided.