Unit 12.03: Documenting known failure modes

The rows worth the most are the ones marked untested.

Failure, mitigation, residual, tested

A fourth column: whether you actually verified the mitigation.

The code lists six failure modes, two of them untested.

FAILURES = [
    ("paraphrases far from document wording may retrieve nothing",
     "logged; weekly review of empty results", "medium", True),
    ("staleness surfaced but not auto-detected",
     "updated date shown in every answer", "medium", True),
    ("citation check is term overlap, not entailment",
     "20 answers manually reviewed weekly", "medium", True),
    ("English only", "non-English queries refuse", "low", True),
    ("concurrent session behaviour", "none", "unknown", False),
    ("index rebuild during a request", "none", "unknown", False),
]
print(f"{'failure':52} {'residual':9} tested?")
for failure, mitigation, residual, tested in FAILURES:
    print(f"{failure:52} {residual:9} {'yes' if tested else 'NO'}")

untested = [f for f, _, _, t in FAILURES if not t]
print(f"\n{len(untested)} known-unknown(s): {untested}")

# The untested rows are the honest part. Listing something you have not tested
# is stronger than omitting it, because a reviewer can weigh it rather than
# discover it.

Concurrent session behaviour and index rebuild during a request have no mitigation and a residual of unknown. Listing them is stronger than omitting them, because a reviewer can weigh a known gap and cannot weigh one they do not know about.

The tested column is what stops a mitigation being aspirational. "20 answers manually reviewed weekly" is only a mitigation if someone is reviewing them, and the column is where that gets confirmed rather than assumed.

The mistake this prevents

The mistake is listing mitigations without recording whether they are verified. A page of mitigations, several of which nobody has run, reads as much better coverage than it is - including to the person who wrote it.

Takeaway

Add a tested column to your failure-mode table and populate the untested rows honestly. A known gap can be weighed; an unstated one is discovered in production.

Mark complete