A successful sequence answers what should happen once. A useful implementation brief also answers what happens when the same intent arrives twice, state changes underneath it, or an external service applies a write but its response never arrives.
Before asking an AI coding agent to implement a change, walk the sequence through those conditions. Use branches to make each decision, side effect, and recovery owner visible. The goal is a small set of meaningful scenarios with different outcomes, rather than a diagram containing every possible exception.
Start at the side effect
Our fictional release-note agent drafts text from repository changes. A maintainer approves a specific revision, the server captures its immutable snapshot, and a Publication Gateway sends it to a Release Host. The agreed policy accepts only the revision current at reservation time; later editing does not change an accepted operation.
Mark the external publication as the side effect. Then ask what the application knows immediately before and after it. Before sending, the application can know the authenticated actor, approved snapshot, target, and operation identity. After a response, it may have a receipt. After a timeout, it may know only that it attempted the call.
That difference changes recovery. A failed validation can be corrected and resubmitted. A sent write with no response requires an outcome check or a retry supported by a verified idempotency contract. HTTP's idempotency guidance cautions against automatically retrying non-idempotent requests without grounds for knowing that this is safe.
Separate the branches that change action
| Condition | State or response | Required next action |
|---|---|---|
| Actor lacks publication authority | Forbidden | Stop before reservation or external publication |
| First approval names an old revision | Stale approval | Show the current draft for a fresh decision |
| Same approved operation is submitted again | Existing operation state | Return pending, unresolved, or the saved receipt |
| A request identity is reused with different content or target | Identity conflict | Reject; do not treat it as a retry |
| Host definitively rejects the write without applying it | Rejected | Explain the verified reason and permitted recovery |
| Host may have applied the write, but no definitive response is available | Unresolved | Reconcile the original operation before creating another |
“Definitively rejects” is a provider-specific classification. Do not assign it to every HTTP error or exception. Some failures happen after an external side effect. Read the adapter and provider contract to determine what each result actually establishes.
For a duplicate, look up the existing operation before treating the current draft revision as a new approval check. If revision 7 was already accepted and revision 8 now exists, a repeated request for the accepted revision 7 should return its operation. It should not accidentally become a new approval or disappear behind a misleading stale-revision error. Authorization still applies to this lookup.
Draw the lost-response scenario
Start a focused sequence with an already reserved operation, pub-42. A worker claims it. The gateway sends the snapshot to the host using the stable operation identity where supported. The host creates the release, but the response is lost. The application records “unresolved” if it can; after a process crash, a reserved or dispatching record must also be investigated.
The maintainer presses Publish again. The server finds pub-42 and returns its unresolved state. It does not generate pub-43 and send the same write as a fresh intent. A later outcome check finds the host's receipt and completes the original operation.
If the host offers no reliable lookup or deduplication mechanism, draw the branch that ends with manual investigation. A local operation table prevents some duplicate dispatches, but cannot make an arbitrary remote API exactly-once. AWS's idempotent API design article discusses stable request tokens, their lifetime, and validation; those capabilities must exist at the relevant boundary.
A “not found” result also needs interpretation. It might mean the write was never applied, or that an index has not caught up. Keep the state unresolved until the provider's documented semantics justify another action.
Live model · Sequence view
Follow the operation after the response is lost
The lost-response scenario distinguishes an external write from the caller's knowledge of its outcome. Repeated requests return the same operation; stale first approval and identity conflict stop at different boundaries.
Explore scenarios in this model
- Architecture view
- G - Generate a draft
- P - Publish an approved snapshot
- S - Reject a stale first approval
- D - Repeat or conflict with publication intent
- U - Remote write with a lost response
- R - Reconcile the original outcome in background
These links open the same public model in a selected view. They do not change its source.
Open this viewer on its own ↗ if the frame is unavailable. The explanation remains readable without the viewer.
Exploration is local to your viewer. Reload or Reset view returns to the source layout.
Turn interleavings into checks
Some failures are caused by the order of otherwise valid operations. Model these with short competing timelines instead of one enormous branch tree.
- A maintainer views revision 7.
- Generation saves revision 8.
- The approval transaction compares the current revision with 7.
- The comparison fails; the gateway receives no request.
Now reverse steps 2 and 3. The transaction captures revision 7 before revision 8 exists. Under our chosen policy, publication of the captured revision 7 may proceed. The two outcomes are intentional. The implementation needs a transaction or equivalent concurrency control that gives the decision a definite point. NightLens's booking-versus-closure protocol works through the same question with two competing writers and a shared slot lock.
Ask the coding agent to propose a test for both orders. Review whether the test controls the interleaving or simply calls two functions sequentially. For duplicate submissions, also test two concurrent attempts to reserve and claim the same operation.
Keep the scenario set manageable
Give a separate sequence to a failure that changes who owns recovery or whether another side effect is permitted. Ordinary input-validation variations can share a table when they all stop at the same boundary. This keeps the important distinctions legible.
There is a trade-off: more scenarios expose more decisions, but also cost more to review and maintain. Prioritize external writes, durable state changes, authority checks, concurrency, and irreversible outcomes. The diagram does not prove that the implementation follows its branches; it tells you what evidence to request.
Try it in Unograph
In Unograph, reuse the publication participants for a lost-response sequence. Show the external write, the missing definitive result, and the later lookup of the same operation. Trace the stale-approval scenario separately. For each stopping point, write down whether another external write is allowed and who decides.
Write a Diagram-Driven Brief for an AI Coding Agent supplies the task this analysis refines. Next, Implement and Verify an AI-Assisted Change Against a Model connects these scenarios to code and focused checks. Return to the release-note agent learning path for the full sequence of lessons.