An AI-generated architecture diagram can make a pull request feel understandable in seconds. A request enters a handler, reaches a service, writes to a database, and returns a response. Every arrow points forward.
Then a dependency fails between two arrows.
That is where a second diagram earns its place in the review: draw what happens when the operation stops halfway through.
Pick one boundary, not every possible disaster
Consider a hypothetical report-export service. A request creates an export record and hands work to a queue. A worker generates the file later.
The happy path is short:
request -> create export record -> enqueue job -> return job ID
worker -> generate file -> mark export ready
Now ask what happens when the queue rejects the job after the record is created. Does the request fail? Does the record remain pending forever? Is there a recovery process? The diagram does not answer those questions. It gives you somewhere precise to ask them.
Choose the behavior your implementation actually supports. Do not let AI silently fill the gap with an imagined retry worker or transaction spanning systems that do not share one.
Make every arrow earn its place
Ask the assistant to associate each arrow with a function, call site, or configuration entry. Mark relationships it cannot verify as uncertain. Keep the requested scope small enough to review.
A useful prompt is: “Trace this export operation through persistence and enqueueing. Show the failure path if enqueueing fails. Cite the code for each transition and identify any recovery mechanism you cannot find.”
This separates a readable explanation from evidence. It also gives the next investigation a concrete target: the transition after the database write, rather than the entire repository.
Turn the gap into an experiment
Use a development environment and a disposable export. Make the queue dependency reject the enqueue operation through a controlled test double or test configuration. Do not break a shared production dependency to reproduce the diagram.
Record both the response and the stored state. A response-only test can miss an orphaned record; a database-only test can miss a misleading success response.
Given: enqueueing is configured to fail
When: a disposable export is requested
Check: the documented response is returned
Check: the stored export has the intended recoverable or terminal state
Check: no export is presented as ready without a generated file
These are illustrative checks, not a product-specific test syntax. Their exact assertions depend on the service's documented policy.
Carry the decision into the API workflow
Once the intended behavior is clear, describe the relevant failure response and job states in the local contract. Use AI to propose the change, review it against the observed behavior, and keep the failing scenario as a regression case.
This is the kind of connected workflow we build for at Powerduck: AI-assisted API work around a local contract, with debugging, scenario testing, documentation, and MCP tools sharing that foundation. A corrected response definition should inform the human reading the docs and the agent invoking the operation.
The contract still cannot prove that a worker will recover a stranded job. Keep that implementation check visible. A useful workspace brings the evidence together; it does not make missing behavior real.
Before approving the next diagram, pick one arrow and ask: if this step fails, what will the caller observe, and what state is left behind? Then run the experiment.
Top comments (0)