Docs Don't Rot, Claims Do: An Expiry Ledger for Model-Drafted Pages

Description and use

Adding an expiry date and a verification command to model‑drafted claim blocks lets stale statements surface before they reach readers.

Problem

Documentation claims become stale because ownership does not track when a claim was last verified.

Outcome

The workflow adds a temporal dimension to documentation claims, ensuring that stale or incorrect statements are identified and addressed before users read them.

Workflow

• 1. Author writes a fenced YAML claim block before the prose, specifying id, class, owner, expires, source, and verify command.
• 2. The model generates the prose body beneath the claim block.
• 3. The verify command is a safe, idempotent script that can run in CI.
• 4. A Python script (doc_expiry.py) scans all Markdown files for claim blocks, parses required fields, and validates them.
• 5. Claims are classified into ok, reverify‑soon, blocked, or contradicted states based on expiry and verify results.
• 6. The CI job runs the script on a schedule; only blocked or contradicted claims fail the build, while reverify‑soon claims are highlighted for review.

Evidence

Binding a human owner to each documentation section fixes accountability at draft time, but it does nothing about the day the claim stops being true.

Source

The workflow below attaches an expiry date and a re-verification command to every claim a model drafts, then runs a ledger on a schedule so stale sentences surface before a reader trips over them.

Source

Each drafted claim lives in a fenced block in the Markdown source that never renders. The verify command must be non-interactive, idempotent, and safe to run in CI.

Source

The ledger classifies every claim into one of four states: ok, reverify‑soon (seven days or fewer), blocked (expired or missing a required field), and contradicted (the verify command returned non-zero).

Source