1 Start with the outcome
An agent is asked to make a downloaded model available to an application. It adds a download operation, writes bytes to disk, returns success, and tests that the file exists. The application still cannot use the model.
Perhaps the model needs a companion file. Perhaps a runtime is missing. Perhaps the local catalog does not know its identity. Perhaps success was announced before finalization finished. These are different defects, but the request left one question unresolved: what does available mean?
This is an illustrative scenario. Its purpose is to show how an implementation can satisfy a literal interpretation while missing the intended result. Puma has described this problem directly: a plan may be logically consistent and still omit an invariant that would have changed what the agent built. Nothing inside the plan necessarily contradicts the omission. Executing the plan more faithfully cannot recover information that never entered it.
An outcome states what becomes possible for someone. An implementation describes how the system makes it possible. The distinction is useful without being absolute. A mechanism can itself be a requirement when compatibility, regulation, interoperability, or a deliberate product choice makes it essential. The developer needs to discover why a requested detail matters before treating it as either binding or disposable.
Find the action after success
For the download example, ask what the consumer should do immediately after receiving success. If the answer is “open the selected version through the supported runtime,” file existence is only an intermediate condition. The system must also make the selection resolvable and establish whatever readiness the runtime requires.
A first outcome statement could be:
After the operation succeeds, the intended local consumer can request the selected resource by its stable identity and begin using it through a supported runtime.
The statement still needs discussion. Does the acquisition operation install the runtime? Does it report missing support? Can it substitute another model? Those choices affect the product and should not be hidden inside an attractive method name.
Now add an unwanted result:
The interface says the operation succeeded, but the consumer receives an artifact it cannot identify or use.
This counterexample gives the team something concrete to exclude. It does not select an architecture. It establishes that “download returned success” is an inadequate acceptance observation for the intended outcome.
The same method works outside model management. If a request says “add export,” ask what the recipient must be able to do with the exported data. If it says “make search faster,” ask which delay is disrupting which activity. If it says “use a graph,” ask what relationships the person needs to see or which decision the graph should support.
Separate purpose from a plausible representation
Suppose a person wants a graph of a codebase. They may be trying to understand dependencies, locate the reason behind a decision, assess the impact of a change, or identify unfinished work. A graph of file imports may help with the first and fail at the others.
A useful question is, “What would you want to notice or decide more quickly?” It respects the suggestion while investigating its purpose. The person might explain that spatial relationships are essential to how they work. In that case, a visual requirement is real. Or they might reveal that they mainly need a reliable answer to “Why is this here?” A graph could remain useful, but the data now needs to include reasoning and provenance rather than merely structural links.
Do not convert this into a ritual in which every request is challenged. If the outcome is clear, the requested mechanism fits, and the change is bounded, proceed. Discovery has a cost. Its value lies in resolving a decision that affects the result.
Keep the domain assumptions visible
Software operates in a world it does not completely control. A program can verify a checksum, but it relies on an expected checksum with a trustworthy origin. It can publish a local path, but it relies on filesystem behavior and permissions. It can ask a process to stop, but the request is not the same event as confirmed termination.
Requirements research distinguishes desired world outcomes, software specifications, and assumptions about the environment. Zave and Jackson's formal account makes the relationship explicit: the software's specified behavior and domain assumptions must together support the required outcome. This is a conceptual foundation, not proof that a particular conversation finds every assumption. Four Dark Corners of Requirements Engineering.
For our resource example, an assumption might be that publishing a reference can be made atomic with respect to readers. If that assumption is false on a supported platform, a correct implementation of the planned sequence may still expose a partial result. Naming the assumption lets someone investigate it before the plan treats it as settled.
Try it on a small change
Choose a request you could implement in a day. Write five short statements:
- The person or component that needs the change
- The action it should be able to perform afterward
- One superficially successful result that would disappoint it
- One environmental assumption needed for success
- One detail whose status as a requirement or preference is unclear
Explain the result back to the requester. Include a consequence they did not explicitly mention. If your export includes private metadata, your faster search returns stale results, or your download silently installs a runtime, that consequence belongs in the discussion.
The artifact should be short enough to remain useful during implementation. It is a reference point, not a promise that no further learning will occur. When the code changes, it gives the team a way to ask whether the new behavior still serves the original purpose.