| name | keep-a-confidence-ledger |
| description | Maintain one honest map of what is actually true about every subsystem in a project. Use when landing or verifying work changes a subsystem's state, at session close, or when someone asks "what's the state of X", "is X done", "how far along are we", "what's actually working". Replaces percentages and vibes with exactly four evidence- backed states, so a handoff or a status answer never overstates reality. |
Keep a Confidence Ledger
Every project accumulates claims about its own state: "auth is done", "search mostly works",
"deploy is 90% there". Most of those claims were true once, for some definition of done,
according to the person who wrote the code. A confidence ledger is the single file that
answers, for every subsystem, the only question that matters at handoff: what is actually
true, and how do we know? A wrong row is worse than a missing feature, because people build
on it.
The four states (exactly one per row, no percentages)
- complete: verification evidence exists and is NAMED in the row: the command, the CI
run, the test count, the date. "Complete" without evidence is a lie with good posture.
- needs-polish: works, with a KNOWN, WRITTEN gap ("no date filter; sorting is
insertion order"). The gap text is the point; "needs polish" alone is banned.
- blocked: waiting on something external, with the EXACT unblock step ("client shares
API keys, then set the secret and run the live smoke test"). A block without an unblock
step is a complaint, not a state.
- future-phase: deliberately not built; points at a dated decision or a scope document
that says so.
No fifth state, no "almost", no "80%". A percentage is a feeling wearing a number; none of
the decisions a reader makes (trust it, fix it, chase the blocker, ignore it) map to one.
Flip rules
- States are set by verification evidence, never by the author of the change. Whoever
wrote the code proposes; the evidence decides. Observed across production agent runs,
author-flipped rows are the single largest source of false "complete".
