From e4a5acb71d6688ca0c46e7113e53341f7678edc3 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 19 Oct 2026 04:18:15 -0400 Subject: [PATCH] docs: require necessity checks in agent plans and reviews --- .agents/architect.md | 13 ++++++++++++- .agents/planner.md | 22 ++++++++++++++++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/.agents/architect.md b/.agents/architect.md index 3e1d77798..b779f818b 100644 --- a/.agents/architect.md +++ b/.agents/architect.md @@ -146,9 +146,13 @@ concept to explain itself. ## Communication rules 1. When the Product Owner says they do not understand, stop and run the five-part understanding interview. -2. Before proposing a new abstraction, show the concrete problem, why existing APIs cannot solve it, and what decision requires the Product Owner. +2. Before proposing an abstraction, trace its production consumer, show why existing APIs are insufficient, and name any Product Owner decision. 3. Explain behavior with familiar words and a concrete example before introducing technical terms; use only terms needed for the current decision. +Tests and fake consumers created only to exercise proposed machinery do not +establish its necessity. Distinguish the accepted requirement from the proposed +mechanism before settling the design. + When the Product Owner says they do not understand, stop the current design discussion and run this interview before continuing: @@ -211,6 +215,13 @@ Before reaching a verdict: with the feedback commit. 5. Trace success, failure, cancellation, replay, teardown and stale-state paths when the change touches them. +6. Assess the necessity of new mechanisms independently of plan compliance; + identify what existing primitives already provide and what can be removed + while preserving the accepted behavior and boundaries. + +An accepted plan or passing tests do not establish that a mechanism is needed. +Return a specific unsupported design assumption for resolution rather than +requiring more machinery to defend it. Review the commit that was handed over, not a remembered or previously reviewed revision. State the reviewed commit in the result. diff --git a/.agents/planner.md b/.agents/planner.md index fa56cf73c..cbccb7cc4 100644 --- a/.agents/planner.md +++ b/.agents/planner.md @@ -84,6 +84,18 @@ Prefer a focused PR stack when independent invariants can be reviewed and merged separately. Do not split work at a point that requires a temporary architecture or leaves `main` contradicting its specifications. +## Mechanism necessity + +Before freezing a plan, justify each new registry, protocol, lifecycle guard or +generic interface. Name the accepted behavior it serves, trace a supported +production consumer and show why existing primitives are insufficient. A test +or fake consumer created only to exercise the proposed mechanism does not +establish its necessity. + +Distinguish accepted behavioral and structural requirements from proposed +mechanics. Do not turn an unsupported mechanism into an acceptance criterion +and then use tests of that criterion to justify the mechanism. + ## Plan contents The plan records: @@ -155,6 +167,16 @@ positive nor negative evidence for this verdict, and it is inspected only when the user explicitly assigns CI troubleshooting. A passing verdict is `PASS` — never `PASS pending CI` or an equivalent condition. +During review, assess necessity independently of plan compliance. Ask what can +be removed while preserving the accepted behavior and boundaries. An accepted +plan or passing tests do not establish that machinery is needed; return a +specific unsupported assumption for plan correction instead of hardening it. + +Apply the repository's comment rule to the final diff. Keep explanations of +surprising constraints; remove narration of names, types and straightforward +code. Lengthy commentary defending a mechanism calls for reconsidering the +mechanism, not adding more explanation. + Planning review closes when the frozen criteria and evidence pass. It does not reopen for CI, diagnostic hardening, speculative permutations, unrelated correctness polish, or a non-blocking observation. A later correction returns