docs(agents): needs-your-hands is binary — a merge gate or nothing

Either the manual check guards an irreversible path and the verdict
reads 'MERGE — after you verify X', or the verdict is a plain MERGE
with no checklist: residual cosmetic risk is absorbed by the verdict
(users surface it, a revert costs one commit). Post-merge homework
lists were the reviewer offloading uncertainty onto the maintainer.
This commit is contained in:
Bohdan Triapitsyn
2026-08-28 15:32:07 +03:00
parent 8b27bd6791
commit 5faa1a6531
2 changed files with 2 additions and 4 deletions
+1 -3
View File
@@ -35,9 +35,7 @@ Choose exactly one. When torn between two, the deciding question is always: **wh
**Link the issues a fix closes.** For every MERGE and MERGE-THEN-FIX verdict on a bug fix, search open issues for the symptom the PR resolves (`gh issue list --search` with the error strings and area terms) — contributors often fix problems without linking them. Any match goes into the ready action as a proposed "Closes #N" / close-on-merge so fixed issues never linger open unlinked.
Manual verification the agent cannot perform (device testing, packaged builds, visual states) does not create a fifth verdict: pick the verdict the code earns and attach a **"needs your hands"** line saying exactly what to check and what outcome confirms it — marked as one of two kinds, chosen by consequence:
- **gate (до мержу)** — the check guards an irreversible or hard-to-revert path: data loss, upgrade/restart flows, auth, anything where users would hit the breakage before the maintainer notices and a revert would not save them. The PR waits for this check.
- **smoke (після мержу, за нагоди)** — low-risk visual or interaction polish where a revert is one commit and the blast radius is cosmetic. Merging first is fine; the line states plainly that skipping the check is accepted risk, not debt — never pad this list to feel thorough.
A **"needs your hands"** line exists only when a manual check GATES the merge — the check guards an irreversible or hard-to-revert path (data loss, upgrade/restart flows, auth, destructive gestures) where users would hit the breakage before the maintainer notices and a revert would not save them. Then the verdict itself says so: "MERGE — після твоєї перевірки X", with exactly what to check and what outcome confirms it. There is no "check later, when you get a chance" kind: a plain MERGE means merge — residual cosmetic risk is absorbed by the verdict, because users surface it and a revert costs one commit. If the reviewer feels the urge to hand the maintainer a post-merge checklist, that is residual uncertainty to either resolve (investigate more) or accept (say nothing) — never to offload.
## Process
+1 -1
View File
@@ -47,7 +47,7 @@ Split the clean pool smallest-first (tiny diffs are fast wins and most likely me
- Every PR/issue reference is a clickable link: `[#3177](https://github.com/openchamber/openchamber/pull/3177)` (issues: `/issues/N`) — never a bare number.
- One entry per PR, 24 sentences: what it does for the user, whether the problem is real, why this verdict, the main risk or the thing the decision turns on. "Closes #N" links included.
- "Needs your hands" lives INSIDE the PR's own entry as a final line, never as a separate section repeating the numbers — a number appearing twice reads as a duplicate.
- A "needs your hands" line appears only when the check gates the merge (per the pr-review skill), and lives INSIDE the PR's own entry as its final line never as a separate section repeating the numbers. A plain MERGE entry carries no checklist.
- Thread-state line first for pickup-mode entries.
- A one-line entry ("точковий фікс") is fine only for genuinely trivial diffs; a verdict the maintainer must weigh (product calls, larger features) gets the full 4 sentences.