“Prepare the charts for tomorrow’s patients” sounds like a small automation request. It can also hide enough unanswered questions to make a functional application fail the clinic using it.
Which schedule counts as tomorrow: the clinic’s local day, the server’s day, or the next 24 hours? Should canceled appointments be excluded? What happens if an outside imaging report is referenced in a note but its contents are unavailable? Who can review the draft, and does producing it change anything in the chart?
These are software requirements. They rarely arrive in the first sentence of the request.
The chart-preparation workflow below is an illustrative pain-management-clinic example, not a description of a specific practice, patient, or clinical recommendation.
How a useful request becomes an incomplete ticket
Imagine a clinic coordinator asking for a morning briefing for the next day’s appointments. The coordinator’s mental model includes the clinic’s time zone, which appointment statuses count, where outside records live, and who may review the material. Much of that knowledge is so familiar that it goes unstated.
A product ticket compresses the request into “generate pre-visit summaries.” An engineer maps it to a scheduling endpoint and a document-generation service. A coding agent creates the integration, a template, and a test confirming that the endpoint returns a PDF. The build passes.
But the application can still include an appointment canceled after the nightly job ran. Or it can produce a briefing with an empty imaging section because the integration could see an attachment’s title but could not retrieve its contents.
Nothing in “returns a PDF” catches either problem. The translation from workflow to ticket discarded the distinction between a document exists and the right evidence is ready for the right encounter.
Make the missing meaning part of the contract
For this example, I would start with five explicit rules:
- Schedule scope: select the next local calendar day using the clinic’s configured time zone, with a documented start-inclusive, end-exclusive interval. Do not assume the server’s time zone.
- Encounter scope: associate the briefing with the intended encounter, and recheck appointment status before marking it ready.
- Evidence scope: attach the source and retrieval time to important statements. Distinguish a retrieved report from a note that merely mentions one.
- Missing evidence: represent “not found,” “not accessible,” and “source request failed” as different states. None means “the patient has no relevant history.”
- Authority: create a reviewable draft. This workflow does not sign a clinical note or make a treatment decision.
These rules constrain the whole implementation. They tell the integration developer what to retrieve, the agent what it may infer, the interface what to show, and the evaluator what to reject.
The test suite should remember the conversation
Create a synthetic appointment close to midnight in the clinic’s local time. Cancel an appointment after the initial fetch. Supply two encounters for the same synthetic patient. Return an attachment reference but deny access to its contents. Make page two of a paginated records response fail.
Each case tests a decision the stakeholder may have assumed was obvious. The expected result is specific: the correct appointment set, the correct encounter association, an explicit incomplete-evidence state, or a blocked publication step.
The model also needs a negative test. If a source says only “outside MRI referenced,” the briefing must not claim the MRI was reviewed or invent its findings. That is a claim-level check, separate from whether retrieval succeeded.
AI can help turn requirements into tests. It cannot recover a constraint nobody preserved or supplied. The useful role of a coding agent is to make the contract executable while keeping unresolved questions visible.
“Check authorization” is not one action
Consider another pain-management workflow request: “check authorization for the scheduled procedure.” A rushed implementation might compress several states into one authorized boolean. But discovering that authorization is required, assembling documents, submitting a request, and receiving a decision are different events.
CMS explicitly distinguishes checking coverage requirements from submitting an authorization request. A coverage-requirements response is not itself a submission. CMS’s Prior Authorization API FAQ illustrates why those states cannot be collapsed.
In an illustrative implementation, retain the source status, requested service, relevant dates, and last successful verification. If the appointment is rescheduled, recheck whether the earlier evidence still applies. Do not quietly reuse an old green badge.
Otherwise staff may believe a task is complete when the application has only completed an earlier step. The failure is in the meaning of “done,” not the fluency of the explanation.
Measure the work that comes back
For chart preparation, generation latency is useful but insufficient. I would also measure briefings with complete source retrieval, those held for missing evidence, reviewer corrections, wrong-encounter associations, and time spent reconstructing the original record.
A system that produces a draft in seconds but requires someone to reopen every source has moved work into a less visible queue. A system that clearly identifies the one missing report may be slower to generate and still be more useful.
This is what I mean by software delivery as a translation problem. Preserve the stakeholder’s meaning in a contract. Carry it into the implementation and evaluator. Bring production failures back as specific regression cases. Faster coding helps most when those connections survive.
A practical review question: Which assumption from the original workflow would still be true if the application returned a successful response with the wrong records?
Written by Morteza Naraghi, co-founder and CTO of Meros AI and author of Agentic Software Delivery.