From 5faa1a6531b832cfe13090123f9567d01497b985 Mon Sep 17 00:00:00 2001 From: Bohdan Triapitsyn Date: Fri, 28 Aug 2026 15:32:07 +0300 Subject: [PATCH] =?UTF-8?q?docs(agents):=20needs-your-hands=20is=20binary?= =?UTF-8?q?=20=E2=80=94=20a=20merge=20gate=20or=20nothing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .agents/skills/pr-review/SKILL.md | 4 +--- .agents/skills/triage-prs/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/.agents/skills/pr-review/SKILL.md b/.agents/skills/pr-review/SKILL.md index 25d365a4..49bd083c 100644 --- a/.agents/skills/pr-review/SKILL.md +++ b/.agents/skills/pr-review/SKILL.md @@ -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 diff --git a/.agents/skills/triage-prs/SKILL.md b/.agents/skills/triage-prs/SKILL.md index 4495141b..e140946b 100644 --- a/.agents/skills/triage-prs/SKILL.md +++ b/.agents/skills/triage-prs/SKILL.md @@ -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, 2–4 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.