[🛠] Operations Automation #4: Preventing Stale State with Fewer Documentation Updates

✨ GPT-5.6 Sol’s Summary

A record of replacing repeated state updates across multiple documents with a single owner for volatile state, conditional downstream updates, and phase checkpoints.

The more documents I kept current, the more the current state diverged

After a long task was compacted or handed off to another session, an old document’s next action was sometimes mistaken for the current state. To prevent that, for a while I updated every document that seemed related whenever the state changed.

I repeated the same completion status and next action in the README, document router, requirements, current-direction document, Runbook, and TODO. It felt safe as long as no document was missed.

But the moment one state change was written in six places, all six had to remain identical. One document stayed at the pre-deployment state while another said real-device verification was already complete. Updating more documents did not prevent stale state. It created new stale state.

Whenever one small verification finished, I also updated several documents and made another commit. Git history became fragmented. It showed how many times the wording had been synchronized more clearly than where the implementation actually ended.

I gave volatile state a single owner

The problem was not the number of documents. It was that several documents owned the same fact. So I first assigned exactly one owner to each kind of fact.

Changed fact	Owner	When to update another document
Current Runtime, blocker, phase, and next action	canonical current-state snapshot	Do not copy them into other documents
Stable product decisions, prohibited workarounds, and active Goal	current-direction document	Only when the product decision or Goal itself changes
Behavior, data, authorization, and acceptance	requirements or contract	Only when the user or system behavior contract changes
Operating procedure, gate, rollback, and recovery	Runbook	Only when the procedure an operator must follow changes
Document relationships, product stage, and execution entry points	README or router	Only when navigation paths or product relationships change
Detailed commands, logs, and worker verification	report, artifact, and Git evidence	Keep only the conclusion and evidence link in aggregate documents

The key is to separate “related” from “owned.” Finishing a deployment does not require changing the requirements. If the deployment changes an operational rollback procedure, update the Runbook. If it also changes the behavioral contract, then update the requirements.

The README and router no longer follow the current revision, device state, or next action either. They point, in a stable way, to what should be read and where execution begins.

I separated immediate updates from durable checkpoints

Having a single owner does not mean delaying documentation until the end of a phase. When new evidence appears or the Runtime state, blocker, priority, or next action changes, the canonical current-state snapshot is updated immediately before the next implementation step. That lets the next session recover the actual state from one place even if compaction or handoff happens in the middle.

Commits, on the other hand, are not created every time one line of state changes. I review the current state once and create a checkpoint only at a boundary that can be independently reviewed and resumed.

• When implementation is complete
• When deployment and post-deployment verification are complete
• When a real-device or user-entry-point E2E result is available, or a blocker is confirmed
• When work is transferred because of an interruption or handoff

Immediate updates exist for resume safety. Phase checkpoints exist so a coherent set of changes can be reviewed and reverted. Treating both with the same rule was what multiplied micro-event commits.

The rule is simpler when a task has no commit authority. Completing review does not create a COMMITTED or CLOSED state. The integration candidate remains frozen, and it is not recorded as durably complete until a real checkpoint exists.

Worker verification stays in reports, not aggregate documents

In parallel work, each worker produces commands, check results, overlapping hunks, and remaining constraints. Copying all of that back into the root TODO, README, and requirements only increases the number of documents the coordinator must read.

Detailed evidence for each worker stays in an immutable report and the Git diff. The current-state snapshot keeps only the integrated conclusion, its current impact, and the path to the evidence. The coordinator reviews reports individually, but does not treat one report as one commit. Multiple reports from the same phase can share one checkpoint after integration verification.

This distinction keeps aggregate documents short without losing detailed verification. The next session reads the current state first, then follows the linked report and Git evidence only when it needs the basis for a decision.

The resume order was violating the ownership rule

After establishing the rules, I reviewed the entire flow and found a surprisingly basic contradiction. The start procedure told a session to read the README first and todo.md second.

The README said not to duplicate volatile state, yet the actual resume procedure read the router before the current-state owner. If old status text remained, the very first judgment could already point in the wrong direction.

So I reversed the order. The session now checks the canonical current state first for the current Runtime, blocker, phase, and next action. It then uses the README and document router to find the repository boundaries and the necessary leaf documents. Stable product decisions come from the current-direction document, and the actual behavioral contract comes from the requirements.

Adding a document-owner table alone was not enough. Whether the reader is a person or an Agent, the actual reading order also has to follow the ownership relationship.

Current scope and remaining limits

I applied this structure to the shared work rules, Operations Automation document routing, the change-documentation manifest, and the parallel-coordination protocol. The skill validator, documentation synchronization check, and diff check passed. However, the changes are still in the local working tree; they have not been committed or deployed.

I also did not rewrite every existing document retroactively. Historical records and detailed reports remain as they are. When the same current-state fact conflicts across active documents, I reduce it to a reference to the owner. Preventing an old document from being read again as the authority for current work mattered more than the mere existence of that old document.

I no longer judge documentation freshness by how many places were updated. The standard is whether, after compaction or handoff, one document is enough to recover the correct current phase and next action—and whether the detailed evidence remains traceable when needed.