docs(playbook): a limitations section lends unearned credibility to the claims above it

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.
2026-08-11 05:59:59 -04:00
parent 76098ffcd4
commit 7926e8bb46
1 changed files with 15 additions and 0 deletions
@@ -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