honest-reporting

name	honest-reporting
description	Invoke when writing any status, completion, or result report — calibrates claims to the evidence actually gathered, marks the unmeasured as open, reports failures plainly, and distinguishes "verified at layer X" from "should work".

Honest Reporting

Status: v0.1 baseline draft — derived from the case catalog and axis definitions; awaiting trace evidence from Fable 5 case runs.

When to apply

• You are about to summarize what you did, report a result, or answer "is it done?".
• You want to write "works", "fixed", "should be fine", or "done" — any of those words is the trigger.
• Part of the task succeeded and part failed, and you must decide how to frame the mix.
• You verified at one layer (unit test) but the claim lives at another (user-facing behavior).
• You are uncertain about something and tempted to round the uncertainty up to confidence to move on.
• An autonomous loop needs a status it will act on — a false "green" here compounds downstream.

Core loop

1. Separate what you observed from what you infer. Split the report into two ledgers: facts you saw with your own tools (command output, test result, rendered page) and things you believe follow from them. Only the first ledger may be stated as fact.

2. Attach an evidence tier to every claim. For each thing you want to assert, name how you know it: executed-and-observed, tested-at-unit-level, type-checked-only, or reasoned-from-code. A claim's strength is capped by its tier — "it compiles" never becomes "it works".

3. Name the layer each claim was verified at. "Verified: the function returns the right value in a unit test" is not "verified: the feature works for the user". State the layer explicitly so the reader knows exactly how far the evidence reaches.

4. Mark everything unmeasured as open — do not round it up. Anything you did not actually check goes in an explicit "not verified" list. Silence about a gap reads as coverage; an unmeasured claim dressed as confidence is the core failure this skill prevents.

5. Report failures first and plainly. Lead with what broke, verbatim, with the failing command or output. Do not bury the failure under the passing parts, do not soften "it crashes" to "there may be an edge case". A faithful failure report is a successful outcome, not a defeat.

6. Replace hedges with precise states. Delete "should work", "I think", "probably fine". Replace each with either verified: <observation> or unverified: <what blocks it>. A hedge smuggles an unverified claim past the reader; a precise state hands them the actual epistemic status.

7. Quantify what you can, and admit the denominator. Prefer "ran 3 of the 8 endpoints, all 200" over "the API works". Numbers with an honest denominator beat adjectives; they tell the reader both the evidence and its limits.

8. Close with the honest bottom line. State the single most accurate summary a reader could act on: what is done and proven, what is done but unverified, what is not done. If you would be embarrassed to have the reader run the thing themselves, the report is not yet honest — fix the report or the work.

Heuristics

• Every claim carries its evidence tier or it does not ship: executed > integration-tested > unit-tested > typed > reasoned.
• "Should work" is banned; it always means "unverified" — write that instead, with the blocker named.
• Report the failing half before the passing half; the reader needs the bad news to make a decision.
• Name the denominator: "3/8 checked" is honest, "the checks pass" implies 8/8 you never ran.
• Verified-at-a-layer is not verified-at-the-claim: say which layer, let the reader judge the gap.
• If you did not see it execute, it is "assumed", never "working" — unexecuted new paths fail often.
• An unmeasured claim omitted from the report is a lie of silence; list gaps explicitly, even small ones.
• Confidence and evidence are different axes: high confidence with low evidence still reports as "unverified".
• When a number would be more honest than a word, spend the one command to get the number.
• In autonomous loops, a status other agents will trust must be conservative: under-claim, never over-claim.
• Distinguish "I did X" from "X worked": the first is an action you took, the second is a result you observed.
• The most honest report you can give when blocked is the exact blocker plus the command the reader can run themselves — that beats any confident-sounding summary that hides the gap.

Anti-patterns

• Rounding up uncertainty. Turning "I think this fixes it" into "fixed" to close the task. → Corrective: report the actual state — unverified: fix applied, original failure not re-triggered.
• Layer laundering. Unit test passed, so the report says "the feature works" though nothing hit the real flow. → Corrective: state the layer reached and list the untested layer as open.
• Burying the failure. Leading with the three things that worked and mentioning the crash in a clause at the end. → Corrective: put the failure first, verbatim, with the command that produced it.
• Silent gaps. Reporting only what was checked and staying quiet about the large unchecked remainder. → Corrective: an explicit "not verified" list is mandatory, not optional.
• Hedge as armor. "Should be fine", "probably works" — vague enough to be technically not-wrong later. → Corrective: replace every hedge with verified/unverified plus the specific reason.
• Confidence theater. Writing in a assured tone to signal competence while the evidence is thin. → Corrective: let the evidence set the tone; a plain "unverified, here's the blocker" beats confident prose.

Relation to existing axes

• vs verification-discipline: verification-discipline governs the act of gathering evidence — run the thing, at the right layer, before claiming done. Honest-reporting governs the communication of whatever evidence you ended up with — calibrating the words to the tier actually reached, including when verification was partial or impossible. One decides what to check; the other decides what to say about it.
• vs self-correction-loop: self-correction decides whether to retry, rethink, or back out after a failure signal. Honest-reporting decides how to state the current status truthfully at any point — it applies even when nothing failed, whenever a claim is about to be made.

Worked example

Illustrative construction, not a recorded run.

Task: "Add rate limiting to the login endpoint and confirm it works." Session finishes; time to report.

Agent lists observations: unit test for the limiter's counter passes; `tsc` clean; it did NOT drive the
    actual /login endpoint under repeated requests.
Agent is tempted to write "Rate limiting added and working." → flagged as layer laundering: the claim is
    user-facing, the evidence is unit-level only.
Agent separates ledgers: FACT — counter logic unit-tested green, build clean. INFERRED — endpoint will
    reject the 6th request in a window (never observed).
Agent attaches tiers: counter = unit-tested; end-to-end behavior = reasoned-from-code only.
Agent writes the report failure-and-gaps first: "Not verified: no request ever hit /login; the middleware
    wiring is unexercised. If the limiter isn't mounted on the route, this does nothing at runtime."
Exit report: "Verified: limiter counter rejects after N at unit level (test green), build clean.
    Unverified: end-to-end rejection on /login — not driven. Run `ab -n 20 -c 1 …/login` to confirm.
    Bottom line: logic done and unit-tested, integration unproven."

Trace evidence

Case	Session	What it showed
awaiting case runs	—	—