From f3fae958efb1c01f3222a1f85c8def4d09c6e79d Mon Sep 17 00:00:00 2001 From: Keysat Date: Thu, 18 Jun 2026 06:39:58 -0500 Subject: [PATCH] adjudicate: present verdicts and both sides in plain terms MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Keep the investigation and the judge's decision rigorous and fact-based, but render everything shown to the owner — both debate sides and the rationale — in plain language. ESCALATE now surfaces an explicit For it / Against it / Judge's lean pair. --- guides/adjudicate.md | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/guides/adjudicate.md b/guides/adjudicate.md index 506109d..d8dbf95 100644 --- a/guides/adjudicate.md +++ b/guides/adjudicate.md @@ -19,6 +19,15 @@ dangerous (it touches data, auth, money, an external surface, or changes observa behavior). You may autonomously recommend *dropping* such an item, but you may never recommend silently *doing* it — anything above the blast-radius line goes to the owner as a brief. +**Decide on the facts; present in plain terms.** The investigation and the judge's reasoning +are rigorous and technical — grounded in what the code actually does, so the recommendation +rests on real facts. But everything *shown to the owner* — both sides of each debate and the +verdict's rationale — must be in plain language a non-specialist can act on: what the item +really is, what doing it gets you, what skipping it costs. Don't assume jargon; when a +technical fact is load-bearing, explain it in a phrase. The owner is judging trade-offs, not +reading a tech spec. (The technical detail stays in the agents' analysis and can be surfaced on +request — it's just not the default presentation.) + ## Phase 1 — Orient & select (no fan-out yet) 1. Read this repo's `ROADMAP.md` and `AGENTS.md` (especially `## Current state`) for context. @@ -48,7 +57,9 @@ allows; within an item the stages are sequential): HIGH (touches data/auth/money/an external surface, or changes observable app behavior). When unsure, classify HIGH. 2. **Build-advocate** and **Drop-advocate** (in parallel). Each receives the item text and the - investigator's findings and argues one side honestly, citing the findings — not speculation: + investigator's findings and argues one side honestly, citing the findings — not speculation. + Reason from the technical facts, but **write the case for a non-specialist**: lead with the + practical stakes and translate any jargon the argument depends on. - *Build-advocate*: the concrete benefit, the cost or risk of leaving it undone, who or what it helps. - *Drop-advocate*: YAGNI, added complexity and maintenance, opportunity cost, whether it's @@ -56,7 +67,9 @@ allows; within an item the stages are sequential): 3. **Judge.** Receives the item, the investigator's findings (incl. blast radius), and both briefs. Decides against the rubric = `how-i-work.md` + this repo's `AGENTS.md`. **Bias to DROP on a tie or low confidence** — these items are already low-priority, so death is the - default unless a clear case is made. Emits a structured verdict (next section). + default unless a clear case is made. Decide on the technical merits, but **write the + rationale it emits in plain terms** (per the principle above). Emits a structured verdict + (next section). ## The three verdicts @@ -73,23 +86,32 @@ allows; within an item the stages are sequential): ## Phase 3 — Report (inline, no file written) -Show the owner one report. No new tracked artifact — the ROADMAP diff and the commit message +Show the owner one report. **Write every line in plain terms** (per the principle above) — no +unexplained jargon, and never let a raw file path or code symbol stand in for the explanation; +say what it means in practice. No new tracked artifact — the ROADMAP diff and the commit message are the durable record (same convention as `/triage`). ``` # Adjudication — — Adjudicated N of M eligible items. -## DROP (ratify to remove) -- — one-line why-not + judge confidence +## DROP — not worth doing (remove on your OK) +- — why it's not worth it, in one plain sentence (judge confidence) -## DO (low blast radius — your go-ahead to schedule) -- — one-line why + the ready plan +## DO — worth doing and low-risk (your go-ahead to schedule) +- — what you'd gain, in one plain sentence + the ready plan -## ESCALATE (your call — balanced brief) -- — build case / drop case / judge's lean / why it crosses the line +## ESCALATE — your call (touches something that matters) +- + For it: + Against it: + Judge's lean: + Why it's yours: ``` +The plain-language "For it / Against it" pair is the heart of an ESCALATE — it's the easy-to-read +two sides the owner weighs. Keep each to a few plain sentences. + ## Phase 4 — Approve, apply, commit 1. **One approval gate.** Wait for the owner to confirm the batch. Never edit `ROADMAP.md` @@ -112,6 +134,8 @@ Adjudicated N of M eligible items. - Ground every argument in the investigator's findings. If the investigator can't read the code or the item is too vague to investigate, say so and ESCALATE it rather than debating in a vacuum. +- Present in plain terms. The report and both sides of every debate must read for a + non-specialist; the technical rigor lives in the decision, not the prose shown to the owner. - Don't read raw inbox items into the debate — nudge the owner to `/triage` first. ROADMAP is the only input. - Preserve the owner's judgment as the gate: propose verdicts, apply only on approval, and