Unit 11.04: Presenting the trace as evidence

The deliverable of this course is not the graph. It is the evidence that the graph behaves as designed, in a form a reviewer can check.

Four questions a reviewer needs answered

Which path did the run take, where did a human intervene, did the irreversible step execute exactly once, and which branches have tests.

The code prints an evidence record answering all four.

import json

evidence = {
    "run_id": "run-8841",
    "question": "what changed in the refund policy?",
    "path": ["research", "draft", "review", "draft", "review", "publish"],
    "revisions": 2,
    "human_gate": {
        "paused_before": "publish",
        "reviewer": "operator-3",
        "edited_fields": ["draft"],
        "approved_at": "2026-07-29T10:22:41Z",
    },
    "irreversible_actions": [
        {"node": "publish", "attempts": 2, "executed_once": True,
         "idempotency_key": "run-8841:publish"},
    ],
    "branch_coverage_in_tests": {"normal": True, "revise": True,
                                 "give_up": True, "error": True},
    "known_limits": ["single reviewer", "no timeout on the human gate"],
}
print(json.dumps(evidence, indent=2))

print("""
This is what a reviewer should be handed, not a screenshot of the graph. It
answers the four questions that decide whether a workflow is deployable: which
path did it take, where did a human intervene, did the irreversible step run
exactly once, and which branches have tests.
""")

path shows the revise loop firing twice before approval - visible behaviour rather than a claim. irreversible_actions reports two attempts and one execution, which is the idempotency guard demonstrated rather than described. branch_coverage_in_tests names all four branches including the error path.

known_limits is what makes the record credible. "Single reviewer, no timeout on the human gate" tells a reviewer where this will fail before they have to find it - and a run with no stated limits reads as an analysis that was not done.

The mistake this prevents

The mistake is presenting a rendered picture of the graph as evidence. The diagram shows what edges exist, which nobody doubted. It says nothing about which path a real run took, whether the guard held, or whether the error branch has ever executed.

Takeaway

Present a run's evidence record, not a diagram: the path taken, the human intervention, proof the irreversible step ran once, branch coverage, and the limits you know about.

Mark complete