[Joey-Magnus]

Dozens of people and AI agents now work on Hookshot at once, and the same problems get picked up twice while others wait. This gives everyone, agents included, one order of work and one path from report to release.

What

• docs/workflow.md:
  • Where work comes from: issues, tracking issues, Discord #bug-reporting / #dev-work / #dev-stuff, and CI.
  • A priority score, severity x reach x confidence. Reach comes from the systems people run: the issue forms' hardware fields, and the Steam hardware survey for the installed base.
  • Hardware tiers a change must not break. Tier 1 is RTX 20-50 and RX 6000-9000 on Windows and Linux, plus the Steam Deck.
  • The lifecycle: triage, claim, fix, test (including a game-free test, run_all, an in-game run and a tested configurations row), PR, review, merge and release (merge release branches back into main), verify.
  • The security lane (#dev-stuff scans first), suggested labels, and a short list for agents.
• scripts/hardware_report.py: recounts the issue forms' GPU vendor, card class and OS with the gh CLI. The numbers in the doc come from it: of 399 issues that named their hardware, AMD 51%, NVIDIA 35%, Intel 3.5%; Windows 57%, Linux and SteamOS 17%. AMD files half the reports while testing is mostly on NVIDIA, so the doc ranks AMD Tier 1 stability up.
• AGENTS.md and CONTRIBUTING.md point to it.

The suggested labels (priority:P0-P3, hw:*, os:*, needs-log, reproduced, claimed) are only suggestions. Creating them is a maintainer's call.

Tested

• tests/run_all.py: 236 passed, 31 skipped.

• scripts/hardware_report.py run against the repository.

• The link to docs/tested-configurations.md resolves once docs: tested configurations, the runs behind the status table #1723 merges.

• docs/worklist.md: the scored, sorted list of open work (severity x reach x confidence), with the fixed-but-unreleased items and rules for picking, adding and moving rows. workflow.md and AGENTS.md point to it, so people and agents pick from the same list.

🤖 Generated with Claude Code

[Joey-Magnus]

@NotRexed this is the organization piece we talked about in #dev-work: one order of work (severity x reach x confidence, reach from the hardware people run), hardware tiers, and the steps from claim to release, so agents and people stop doubling up. Suggested rollout: pin a pointer in #dev-work, tell agent users to start from AGENTS.md (most agents read it on their own), and create the suggested labels so the issue board becomes the to-do list.