Specify visible state, not just a shared screen.
Two people look at the same screen. One thinks the work is done, the other thinks it's waiting on a carrier, and an agent reading it will confidently pick a side. Trust comes from state kept in a record, not implied by a color.
Ops software earns trust when proposed, in progress, waiting, done, and failed/partial are observable in a shared system of record—with evidence for each transition. Write a Visible State Spec so humans and agents conclude from the record, not from a shared screen or a chat summary.
A shared screen is not shared state
Two people can look at the same screen and believe different things. One thinks the work is done. The other thinks it is waiting on a carrier. An agent reading the same screen will pick a side with confidence.
Ops software earns trust when the state is in a record: proposed, accepted, in progress, waiting, done, or failed. Not when it is implied by a dashboard color or a chat summary.
Write the states people must distinguish
For one workflow, list the states an operator must tell apart without calling a coworker.
Proposed. Drafted or suggested. Not committed.
Accepted. In the system of record.
In progress. Someone or something is actually working it.
Waiting. Blocked. Name what it is blocked on. "Pending" alone is fog.
Done. The exit criteria are met in the authoritative record.
Failed or partial. Stopped. Which steps completed, which did not, and what is unsafe to retry.
For each transition, write what evidence proves it, and who or what may cause it. If "done," "complete," and "closed" mean different things, collapse them or outlaw the extras in the interface.
If two tools each have a done, write both meanings, then pick an authority or an explicit reconciliation. Ambiguous synonyms are how private spreadsheets get born.
How the work moves
Specify states operators must see
- Proposed
Drafted or suggested; not yet committed to the record.
- In progress / waiting
Active work or a named dependency that blocks progress.
- Done
Exit criteria met in the authoritative system of record.
- Failed / partial
Stopped with completed steps visible and a safe next action.
A shared screen is not shared state.
Waiting and partial failure are the product
Most specs describe the happy states and wave at the rest. Waiting and partial failure are exactly where trust dies.
Waiting has to name the dependency. Partial failure has to be findable: what finished, what did not, what must not be retried blindly. If operators cannot answer those from the record, they will invent a tracker. An agent will then summarize the tracker as if it were truth.
Agents need the record
An agent that concludes from a screenshot, or from the last chat message, will be fluent and wrong. Bind what it is allowed to say to fields in the record.
Do that before you widen what it is allowed to do. A wider agent on foggy state does not save time. It spreads the fog.
Decision guide
Shared record vs shared screen
| Consideration | Shared record | Shared screen only |
|---|---|---|
| Done | Evidence fields confirm completion in the system of record. | A green badge that two tools interpret differently. |
| Waiting | Dependency is named and visible. | Generic pending with no owner or blocker. |
| Partial failure | Completed vs incomplete steps are inspectable. | Retry guesswork after a vague error. |
| Agent claim | Bound to recorded evidence before reporting success. | Fluent chat summary treated as truth. |
Put this into practice
Draft the states for one workflow. Mark every status string in the interface against the list. Retire the fog labels. Define the evidence for done, waiting, and partial failure.
Review it with the people who currently reconcile reality by hand, then with engineering. If your backlog only funds happy-path screens, schedule the waiting and partial-failure slice before you celebrate a launch.
That application work sits under web applications.
Related work: Sutton Place.
We build alongside the people doing the work.
Bring us the problem you’re thinking about.