show-your-work

Show Your Work

A decision is easier to trust when the evidence is visible. Publish a decision record, not a transcript of private thought.

What to publish

After a complex audit, plan, redesign, or investigation, add a compact Decision record beside the deliverable with these sections:

1. Evidence used. The files, commands, or sources that support the result.

Cite exact locations. Label anything inferred.

1. Alternatives rejected. Options considered and why each lost. This

answers "why didn't you do X?" without forcing the reader to ask.

1. Uncertainty. What was not checked, what is stale, and what would change

the conclusion.

1. Pivot, if any. The finding that changed the approach, stated as a fact

rather than a story.

1. Next verification. The cheapest check that would falsify the result.

Procedure

1. State the decision in one sentence.
2. Attach the evidence for that sentence, closest source first.
3. List the alternatives that a reasonable reviewer might expect.
4. Mark each unresolved item as unknown or deferred; never fill a gap with

confident wording.

1. Keep the record short enough to read before the deliverable.

Private reasoning stays private

Do not publish hidden chain-of-thought, scratch deliberations, or requests for the model to reveal internal reasoning. Publish conclusions, evidence, and uncertainty instead. A reviewer needs reproducibility, not a monologue.

Good evidence

• file:line for a code claim
• command output with the command shown
• source title and date for an external claim
• "inference" when no direct source exists

Worked example

A compact decision record with evidence, a rejected alternative, and an unknown.

Decision: move retries out of the executor into the provider client.
Evidence: executor.py:412-460 (retry loop), provider.py:88 (single attempt), issue #214.
Rejected: keep retries in the executor; it couples budget accounting to transport.
Unknown: whether the provider retries idempotent POSTs; owner asked to confirm.

Anti-patterns

• A confident narrative with no citations.
• Listing alternatives nobody would have chosen, to look thorough.
• Performing certainty where the evidence is partial.
• Publishing private deliberation instead of a decision record.
• Generic praise ("did great work") in place of method.

Verification Checklist

• [ ] The decision is stated in one sentence. (step 1)
• [ ] Every factual claim has a citation or an inference label. (step 2)
• [ ] At least one rejected alternative is named with a reason. (step 3)
• [ ] Remaining uncertainty is explicit. (step 4)
• [ ] The record contains no request for hidden reasoning. (step 5)