Project: rewrite an incident status notice without changing its claim

Last updated: 7 Oct 20265 min read

project

Create a customer-readable status notice that preserves service identity, timing, uncertainty and the condition governing a possible failover.

Prepare the source and audience

Use a fictional operations update: gateway-west may fail over after 47 minutes if replica health stays green. Add a second version where health is unknown and a third where the expected time moves. Annotate service, event, certainty, duration, condition and action. Write questions a customer must answer after reading the notice. Group revisions of one incident in the same evaluation split. Protected facts form the first gate.

Generate candidate notices

Give the editor a structured fact record and the source paragraph. Permit shorter sentences and definitions of unfamiliar terms, but prohibit unsupported promises. Keep the machine service identifier available even if a friendly label appears. Map each output claim to its source span and revision. If the source says the replica state is unknown, the output must not imply that failover is scheduled or confirmed.

Run reader and editor checks

Compare answers to the source and candidate notice for which service is affected, what may happen, when and under which condition. Test both a reader familiar with incident terminology and a reader without that context. An editor must inspect negation and certainty even if the automatic checks pass. Comprehension checks report differences instead of hiding them in an overall score.

Gate revisions

Store the source revision, protected facts, reader-test results and editor decision. Invalidate the notice when a source value or condition changes; do not patch one number into an old sentence without reevaluating its meaning. The code below represents the final admission state. It does not publish text by itself or assert that a matching token list proves semantic equivalence.

Implementation

def admit_plain_notice(candidate):
    required = ("source_revision", "service_id", "duration_text",
                "condition_checked", "reader_answers_match", "editor_id")
    if any(not candidate.get(field) for field in required):
        return {"state": "hold", "reason": "incomplete-review"}
    if candidate.get("certainty_changed"):
        return {"state": "hold", "reason": "certainty-shift"}
    return {"state": "editor-ready", "source_revision":
            candidate["source_revision"]}

notice = {"source_revision": "incident-r47",
          "service_id": "gateway-west", "duration_text": "47 minutes",
          "condition_checked": True, "reader_answers_match": True,
          "editor_id": "editor-82", "certainty_changed": False}
assert admit_plain_notice(notice)["state"] == "editor-ready"
assert admit_plain_notice({**notice, "certainty_changed": True}) == {
    "state": "hold", "reason": "certainty-shift"}

Performance and operating cost

The fixed-field gate takes O(1) time and space. Generating candidates and conducting reader tests cost more and depend on document length and audience size. The editor-ready state allows final human review, not automatic publication or an assertion that the notice is factually complete.

Common Mistakes

Turning a possible failover into a promised event.
Removing the condition to shorten the notice.
Testing comprehension only against the rewrite and not the source.
Keeping a notice after the incident source revision changes.