From 7926e8bb46463ad52d169a137b6a2a0f1e725049 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 11 Aug 2026 05:59:59 -0400 Subject: [PATCH] docs(playbook): a limitations section lends unearned credibility to the claims above it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Readers take 'what I could not establish' as evidence the rest was held to that standard. Write the claim the evidence licenses, not the broader one; and when two items in your own not-established list contradict each other, flag it — that contradiction is the strongest lead you have, not another unknown. --- admin_ui_cleanup.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/admin_ui_cleanup.md b/admin_ui_cleanup.md index c64e9df..33b040e 100644 --- a/admin_ui_cleanup.md +++ b/admin_ui_cleanup.md @@ -447,6 +447,21 @@ A proof about the container is not a proof about the member, and that substituti because the evidence is real and the reasoning feels airtight. Ask explicitly: *does my evidence range over exactly the thing I am ruling out, or over something that contains it?* +**A "what I could not establish" section confers unearned credibility on everything above it.** +Listing your limitations is good practice and this playbook demands it — but be aware of what it does +to a reader: the presence of a limitations section is taken as evidence that the rest was held to +that same standard. It usually wasn't. A real example from this round: a `pending.md` entry recorded +"do not fix this service" on evidence that actually supported only the narrower "a real shutdown does +not drop events," and its own Not-established section listed two statements that **cannot both be +true** (the executing task is awaited on stop; the loop never ran before stop returned) without +flagging the contradiction. Adjacent bullets under an honest heading read as thoroughness and +function as a dead end for whoever picks it up. + +Two habits follow. **State what each piece of evidence licenses, not just what you believe** — if the +evidence covers a narrower claim than the one you are writing, write the narrower one. And **when two +items in your own limitations list conflict, say so explicitly**; a contradiction is a lead, and +burying it in a list of unknowns converts the most informative thing you have into noise. + **A correction is not automatically safer than the claim it replaces.** The first item above was corrected to "HistorianGateway has no block, so the bump restyles it" — which was *also* wrong, for a new reason: it had no Bootstrap button call sites either, so the kit's rule matches nothing. The