From 658fc722240faab5e6e2fe17cfd19cc0bb77188d Mon Sep 17 00:00:00 2001 From: Aaron Breckenridge Date: Mon, 31 Aug 2026 11:29:23 -0500 Subject: [PATCH 1/2] Close the exemptions reviewers invent to approve a TODO The completeness rules already blocked deferred work unless the ticket or PR discussion accepted the scope-down, but nothing said who may supply that acceptance or what evidence counts. A review pass could therefore assert one on its own -- calling a TODO "a deliberate design choice" or "a documented out-of-scope backlog item" with no ticket and no author statement behind either phrase -- and approve. Make the exemption evidentiary: quote the granting sentence from the ticket or from the author, or request changes. Name the rationalizations that have been used to wave a TODO through so they cannot be reached for again, and say plainly that a well-written TODO is a worse finding rather than a lesser one, since a comment that explains the consequence proves the author knew. --- prompts/_shared/completeness-rules.md | 34 +++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/prompts/_shared/completeness-rules.md b/prompts/_shared/completeness-rules.md index e1f99c5..66b742d 100644 --- a/prompts/_shared/completeness-rules.md +++ b/prompts/_shared/completeness-rules.md @@ -32,6 +32,40 @@ treat this as a blocking issue and request changes. admission of incomplete work. - Unless the ticket or PR discussion explicitly documented and accepted scoping down the work, any unilateral deferral of required functionality must be rejected. + - The exemption above is narrow and evidentiary. To invoke it you must quote the specific + sentence that grants it, from one of exactly two places: the ticket (its description, + acceptance criteria, or an out-of-scope section), or the PR body or a PR comment written + by the author. If you cannot quote such a sentence, the deferral is unilateral and you + must request changes. A reviewer, including you, cannot supply the acceptance. + - A reviewer raising the deferral is not acceptance of it. If an earlier review pass, a + Codex finding, or a bot comment flagged the same TODO, that is corroboration that it is + a defect, never evidence that it was agreed. Do not treat "already discussed" or + "raised in an earlier round" as resolution unless the author responded and the quoted + sentence appears. + - Silence is not acceptance. A ticket that does not mention the deferred work has not + approved it, and an out-of-scope section that lists other things has not implicitly + listed this one. Absence of a prohibition is not a grant. + - A well-written TODO is a worse finding, not a lesser one. The comment's own quality -- + that it names the affected classes, explains the consequence, reads as considered, or + documents exactly what is missing -- is the admission of incomplete work, and it + establishes that the author knew the gap was there. Never treat clarity, detail, or an + articulate rationale as evidence that the omission was sanctioned. + - The following are NOT valid reasons to approve a TODO, a placeholder, or deferred work. + Each has been used to wave one through and none is acceptable. Do not write any of + them, in these words or paraphrased: + - "deliberate", "intentional", "a design choice", "a considered trade-off", or + "reflects a deliberate separation of concerns" + - "a documented backlog item", "tracked separately", "a known follow-up", or + "out-of-scope backlog" -- when no ticket or quoted author statement says so + - "not incomplete PR scope", "orthogonal to this PR", or "belongs to a different layer" + - "the comment explains why", "clearly documented", or "the author was transparent" + - "an accepted boundary trade-off", "a pragmatic cut", or "does not warrant blocking" + - "invalid", "does not apply", or "already resolved" applied to a completeness finding + from the first pass, unless you confirmed in the diff that the flagged comment or + placeholder is gone or was never deferred work -- name the file and line you checked + Inventing an authorization the ticket and the author never gave is the failure this rule + exists to prevent. When you are tempted to explain why a TODO is acceptable, that + impulse is itself the signal to request changes instead. 3. Placeholders, stubs, and mock implementations: - Flag any placeholder functions, stub implementations, hardcoded dummy return values, From 6c4f972de8e1bc8894179734a6fac2cf2cb548f9 Mon Sep 17 00:00:00 2001 From: Aaron Breckenridge Date: Mon, 31 Aug 2026 11:54:28 -0500 Subject: [PATCH 2/2] Tighten the wording of the TODO exemption rules Same constraints, imperative and roughly half the lines. --- prompts/_shared/completeness-rules.md | 46 +++++++++------------------ 1 file changed, 15 insertions(+), 31 deletions(-) diff --git a/prompts/_shared/completeness-rules.md b/prompts/_shared/completeness-rules.md index 66b742d..076d249 100644 --- a/prompts/_shared/completeness-rules.md +++ b/prompts/_shared/completeness-rules.md @@ -32,40 +32,24 @@ treat this as a blocking issue and request changes. admission of incomplete work. - Unless the ticket or PR discussion explicitly documented and accepted scoping down the work, any unilateral deferral of required functionality must be rejected. - - The exemption above is narrow and evidentiary. To invoke it you must quote the specific - sentence that grants it, from one of exactly two places: the ticket (its description, - acceptance criteria, or an out-of-scope section), or the PR body or a PR comment written - by the author. If you cannot quote such a sentence, the deferral is unilateral and you - must request changes. A reviewer, including you, cannot supply the acceptance. - - A reviewer raising the deferral is not acceptance of it. If an earlier review pass, a - Codex finding, or a bot comment flagged the same TODO, that is corroboration that it is - a defect, never evidence that it was agreed. Do not treat "already discussed" or - "raised in an earlier round" as resolution unless the author responded and the quoted - sentence appears. - - Silence is not acceptance. A ticket that does not mention the deferred work has not - approved it, and an out-of-scope section that lists other things has not implicitly - listed this one. Absence of a prohibition is not a grant. - - A well-written TODO is a worse finding, not a lesser one. The comment's own quality -- - that it names the affected classes, explains the consequence, reads as considered, or - documents exactly what is missing -- is the admission of incomplete work, and it - establishes that the author knew the gap was there. Never treat clarity, detail, or an - articulate rationale as evidence that the omission was sanctioned. - - The following are NOT valid reasons to approve a TODO, a placeholder, or deferred work. - Each has been used to wave one through and none is acceptable. Do not write any of - them, in these words or paraphrased: + - Exempt a deferral only by quoting its granting sentence from the ticket or from the PR + body or an author-written PR comment. A reviewer cannot grant acceptance. + - Treat a reviewer or earlier review pass raising the deferral as corroboration of a + defect, never proof of agreement. + - Silence is not acceptance. An out-of-scope list of other items does not include this + one implicitly. + - Treat a clear, detailed TODO as worse: its quality proves the author knew of the gap. + - Do not use these rationalizations, verbatim or paraphrased: - "deliberate", "intentional", "a design choice", "a considered trade-off", or - "reflects a deliberate separation of concerns" - - "a documented backlog item", "tracked separately", "a known follow-up", or - "out-of-scope backlog" -- when no ticket or quoted author statement says so - - "not incomplete PR scope", "orthogonal to this PR", or "belongs to a different layer" + "deliberate separation of concerns" + - "a documented backlog item", "tracked separately", or "a known follow-up" without a + ticket or quoted author statement + - "not incomplete PR scope", "orthogonal", or "belongs to a different layer" - "the comment explains why", "clearly documented", or "the author was transparent" - "an accepted boundary trade-off", "a pragmatic cut", or "does not warrant blocking" - - "invalid", "does not apply", or "already resolved" applied to a completeness finding - from the first pass, unless you confirmed in the diff that the flagged comment or - placeholder is gone or was never deferred work -- name the file and line you checked - Inventing an authorization the ticket and the author never gave is the failure this rule - exists to prevent. When you are tempted to explain why a TODO is acceptable, that - impulse is itself the signal to request changes instead. + - Call a first-pass completeness finding invalid or already resolved only after checking + the diff; name the file and line checked. + - If you want to explain why a TODO is acceptable, request changes instead. 3. Placeholders, stubs, and mock implementations: - Flag any placeholder functions, stub implementations, hardcoded dummy return values,