“Make retries safe” is a request to investigate. It is not yet an implementation contract.
The missing information is not necessarily available to the person writing the ticket. That is normal. A useful specification distinguishes a decision already made from a question the agent must investigate. An agent can ask good questions; a workflow should require it to stop when the unanswered question controls the outcome.
The Northstar case gives us a concrete request. Every identifier and number below belongs to that fictional case.
ORD-42, ready for a bounded attempt
| Field | Accepted task definition |
|---|---|
| Outcome | Repeating the same authorized order request within the retention window creates at most one order. |
| Evidence of need | Three synthetic reproductions based on support reports; production incidence unknown. |
| Governing decision | ADR-17: account-scoped key, payload matching, concurrent safety, 24-hour illustrative retention. |
| Allowed changes | Sandbox Orders handler, persistence code, and tests. Propose schema changes for review. |
| Non-goals | External payment processing, historical deduplication, identity changes, production migration. |
| Inputs | Versioned CTX-42 bundle and synthetic fixtures. No customer data or production credentials. |
| Deliverable | Reviewable patch, test evidence, unresolved limitations, and a proposed rollout/recovery plan. |
| Authority | Local implementation and sandbox checks only. Owner approval required for scope expansion or release. |
| Stop conditions | Conflicting policy, unclear account scope, required access outside sandbox, or inability to test the atomicity assumption. |
The ticket points to authoritative context instead of copying the entire knowledge base. It binds one attempt to a known revision. If ADR-17 changes halfway through execution, the coordinator pauses and decides whether to rebase the plan or discard the attempt.
Write acceptance examples before prescribing code
| Input or failure | Expected evidence |
|---|---|
| Same key, account, and payload, sequential retries | One order; recorded outcome returned. |
| Same key and account, different payload | Explicit conflict; no second order. |
| Same key used by different accounts | Separate authorization and deduplication scopes; no cross-account response disclosure. |
| Two matching requests arrive concurrently | At most one committed order. |
| Process dies before commit | No partial order/result state survives. |
| Commit succeeds but response is lost | Retry returns the recorded outcome after authorization is checked. |
| Retry arrives after retention expiry | Behavior matches the documented expiry contract; no promise of indefinite deduplication. |
These examples constrain behavior without forcing a particular class name or framework. The implementation may discover that the existing storage design cannot satisfy the contract. Reporting that incompatibility is successful investigation, not failed obedience.
Use strong requirement words sparingly. RFC 2119 defines obligation levels for specifications. Borrowing that discipline helps separate a required safety property from a preferred implementation style. Writing MUST in capitals does not make an untestable requirement executable.
Unknowns deserve their own output
Before coding, the agent returns a compact readiness assessment: authoritative sources found, open questions, proposed evidence, and requested permissions. For ORD-42, a missing retention decision blocks implementation because it affects storage and client semantics. A choice between equivalent helper names does not.
If the task is exploratory, say so. The deliverable can be two candidate designs, a benchmark, or a list of contradictions. Do not demand a production patch from a discovery task merely because the agent can produce one.
Keep a change log for material specification revisions. A reviewer must be able to tell whether the patch failed the agreed task or the task changed after the patch was written. Otherwise every review becomes a negotiation about what “done” used to mean.
Scale the contract to the consequence
A spelling correction needs a target, intended replacement, and a quick check. It does not need ORD-42’s acceptance matrix. A migration with irreversible side effects needs more than this example, including recovery ownership and validation in a representative environment.
Specification effort earns its place when it reduces ambiguity that matters. Ask which field prevented a real misunderstanding. Remove fields that nobody consumes. Keep the permission and stop boundaries even when the prose is short.
Size the task by coherence
Traditional planning breaks work into the smallest piece one person can manage. An agent workflow can aim for a different boundary: the largest coherent piece of work the system can reliably execute and validate with the context and checks it actually has. ORD-42 is one intent. The handler, persistence code, tests, and proposed rollout note all serve it. Splitting them into four tickets would force each attempt to reconstruct the same context and carry decisions across boundaries where assumptions drift.
Three quantities set that boundary. Context capacity is what the model can accept. Effective context is what it can use reliably for this kind of work. Task context demand is what the change actually requires. A task can fit the first and exceed the second. Hierarchical context lowers demand by making the governing decisions easy to locate, and stronger validation raises how much scope can be trusted. A broad refactor behind comprehensive tests can be safer than a small change in an untested module.
Coherence is the test, not size. ORD-42 should not also absorb a payment-provider upgrade because both touch Orders: unrelated work shares little context and mainly enlarges the failure surface. Size the first attempt from the intent, the required context, and the available evidence, then let the plan contract. If the readiness assessment or the attempt shows that context is insufficient, split the work and record why instead of pushing a failing attempt further.
Scope and authority remain separate fields. A task can span the whole change while the agent is authorized only to prepare it for review.
Treat these as heuristics to test against first-pass acceptance and rework, not as fixed rules. Evaluation and Release Evidence describes how to measure where the reliable boundary currently sits.
Try the handoff before execution
Give the proposed ticket to someone who did not attend the discussion. Ask them to identify the outcome, prohibited actions, success evidence, and the question that would make them stop. Let them explain the task back without offering hints.
If their interpretation differs, repair the ticket before accelerating execution. Preserve one deliberately ambiguous example in the team’s evaluation set: a capable system should ask for the missing decision rather than confidently completing a different task.
Continue with Agentic Development for the execution loop and Evaluation and Release Evidence for testing the result independently of the agent’s explanation.