From 1cf8768af0db595b95bd0bf847afcdd326f908ef Mon Sep 17 00:00:00 2001 From: Joe Beda Date: Sun, 26 Jul 2026 14:40:43 -0700 Subject: [PATCH] docs(rules): say who runs /code-review, and what to do when nobody can Step 2 of the review loop read 'Run /code-review against the resulting diff', phrased as an instruction to the agent. It isn't one an agent can follow: /code-review is user-invoked and billed to the user, and cannot be launched through the Skill tool, Bash, or any workaround. An agent reading the rule literally either stalls or quietly skips the step, and skipping it silently is the worse of the two. Split step 2 by who is present. Working synchronously, the agent prompts the user to run it and says which tier the change warrants -- that path is preferred, since it is the real thing and the user decides what merges anyway. Running autonomously, the agent approximates with independent reviewer subagents plus the adversarial binary run, which needs no slash command, and must not describe the approximation as if /code-review had run. The tier names in 'Scale round one' were written as /code-review arguments, so they now name the depth itself: the argument when the user runs it, the number of finder angles when approximating. Round records say which path was taken. Co-Authored-By: Claude Opus 5 (1M context) Signed-off-by: Joe Beda --- .claude/rules/agent-workflow.md | 42 +++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 7 deletions(-) diff --git a/.claude/rules/agent-workflow.md b/.claude/rules/agent-workflow.md index d5ec800..16c7d3e 100644 --- a/.claude/rules/agent-workflow.md +++ b/.claude/rules/agent-workflow.md @@ -19,7 +19,8 @@ few hundred lines, goes through this loop: 1. Launch a subagent (`Agent` tool, `isolation: "worktree"`) to implement the change on its own branch. -2. Run `/code-review` against the resulting diff. +2. Review the resulting diff. `/code-review` is user-invoked and an agent + cannot launch it — see "Who runs the review" below for what to do instead. 3. Fix what the review finds via a separate fix subagent, not by hand-editing the result inline. 4. Repeat review then fix for up to three rounds. Record each round's findings @@ -30,6 +31,31 @@ few hundred lines, goes through this loop: 5. If the cap is hit with real issues still open, say so plainly in the final round's record. Never quietly declare the change done. +## Who runs the review + +`/code-review` is triggered by the user and billed to them. An agent cannot run +it — not through the Skill tool, not through Bash, not by any workaround. Step 2 +therefore resolves one of two ways, and the round record must say which. + +**Working synchronously**, with the user present: prompt them to run it, and say +which tier the change warrants and why. Wait for the findings rather than +reviewing around them. This is the better path — it is the real thing, and the +user is already the one who decides what merges. + +**Running autonomously**, or when the user would rather not be interrupted: +approximate it, and never describe the approximation as if `/code-review` ran. +The approximation is: + +- Independent reviewer subagents, one per finder angle the change warrants (see + the tiers below), each held to the evidence standard in this document. +- The adversarial pass, which needs no slash command and is the highest-yield + finder for a format tool: build the real binary and run it against hostile + fixtures, base against change. + +Offer the branch or PR afterwards so the user can run the real review when it +suits them. An approximated round is a reason to keep a pull request in draft +if the change is correctness-critical and the user has not yet looked. + ## Draft until vetted When a change flows through a pull request, open it as a draft as soon as the @@ -52,17 +78,19 @@ draft open and says so plainly. ## Scale round one to the change The full fan-out is not the default. Match the first round's depth to what the -change puts at risk: +change puts at risk. The tier names the depth, whichever path step 2 took: it is +the argument to `/code-review` when the user runs it, and the number of finder +angles to cover when approximating. -- **Full round** (`/code-review high`, all finder angles): changes touching +- **Full round** (`high`, all finder angles): changes touching correctness-critical surfaces — the schema and its sync with the model structs, the version registry and dispatch, the lint rules (structural, semantic, completeness), the Markdown and Mermaid renderers and their deterministic output, or the release and Action plumbing. Also for diffs beyond a few hundred lines, new mechanisms, or new dependencies. -- **Reduced round** (`/code-review medium`): everything else. The cleanup - angles (reuse, simplification, efficiency) earn their tokens only in a full - round; `/simplify` covers them on demand. +- **Reduced round** (`medium`): everything else. The cleanup angles (reuse, + simplification, efficiency) earn their tokens only in a full round; + `/simplify` covers them on demand. - **Docs-only diffs**: one reviewer pass. For a schema-reference or format doc that pass includes a lifecycle walkthrough: take every format concept the doc introduces and walk it through authoring, linting, and rendering from a @@ -74,7 +102,7 @@ references, dangling enum types, completeness gaps), comparing base against the change. For a format tool it is consistently the highest-yield finder. Attribute every finding in the round record to the angle or agent that sourced -it. +it, and record whether the round was a real `/code-review` or an approximation. ## Evidence standards