From 9b2618cac6a6f3158b027aa26cd0a432f16fe4f3 Mon Sep 17 00:00:00 2001 From: Oleh Omelchenko Date: Tue, 30 Jun 2026 17:37:37 +0300 Subject: [PATCH] Docs: deferred review findings get a durable breadcrumb, not a chat mention --- CLAUDE.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b437ad6..f239be4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -70,7 +70,11 @@ run the review pass **before** anything is committed: sweeps stay a deliberate act). Run the subagents **sequentially**, not in parallel — both may edit the working tree. -Relay each report back to the user. Arbitrate findings that needed session context: -either accept them, or overrule them **and** record the missing rationale where the -reviewer looked for it — an overruled finding without a writing-down will recur. Then -commit only when invited. +Relay each report back to the user, then arbitrate each finding to one of three ends — +**accept and fix**, **accept but defer**, or **overrule** — and **write down the two you +don't act on now**, because a subagent's report is ephemeral and chat is not a record. A +deferred finding gets a `// TODO:` at the relevant code site (or a line in the closest doc); +an overruled one records the missing rationale where the reviewer looked. Out of scope for +_this session_ is not out of scope for the _project_: with a single maintainer there is no +"someone else's problem", so an unrecorded deferral or beyond-scope note recurs as work +handed to your future self. Then commit only when invited.