From 32e935755fbcb7ecc1700f3e18980fc93feef5bd Mon Sep 17 00:00:00 2001 From: serenakeyitan Date: Thu, 16 Apr 2026 15:49:03 -0700 Subject: [PATCH] docs: clarify who sets breeze:human (responder-elevated pattern) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DESIGN.md already specifies the four states (new / wip / human / done) but doesn't say who transitions wip → human. This matters because reviewers and agents may both think it's the other's job, leading to PRs that never escalate. Adds a subsection after the Four States table: - Signal comes from reviewer behavior (repeated CHANGES_REQUESTED etc.) - Action is taken by the agent that tracks attempts across rounds - Suggested threshold: 5 rounds Keeps breeze-runner and gardener-respond consistent. Closes #12 Co-Authored-By: Claude Opus 4.6 (1M context) --- DESIGN.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/DESIGN.md b/DESIGN.md index 09485f0..ec32aca 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -225,6 +225,27 @@ Status lives on **GitHub as labels**, not in a local file. The source of truth i The statusline only counts `new` notifications. PRs that are merged or issues that are closed are treated as `done` automatically — no label required. +### Who sets `breeze:human` + +`breeze:human` is labeled by **the agent attempting the work**, not by reviewers. + +The signal for escalation comes from reviewer behavior (repeated `CHANGES_REQUESTED`, unclear feedback, or explicit "needs human judgment"), but the action — setting the label — is taken by the agent that tracks context across rounds. + +**Why the agent, not the reviewer:** + +- Reviewers only know the current PR state, not how many rounds this is +- The agent is the one that knows "I've tried 5 times and the reviewer still isn't satisfied" +- Reviewers shouldn't need to count attempts to do their job + +**Pattern:** + +1. Agent tracks attempts (e.g. HTML marker in PR body: ``, or local state) +2. On each round, agent reads the counter and decides whether to continue or escalate +3. After N failed rounds (suggested threshold: 5), the agent labels `breeze:human` and comments explaining why +4. The human reviewer now knows the agent has given up and manual intervention is needed + +**The rule:** reviewer behavior provides the signal; the agent takes the action. + ### Statusline only shows `new` count ```