RoundsCorrowmere Clinics · Estmark synthetic data · seed 23

How Rounds works

A ten-minute read. The full version, module by module, is in architecture-full.md. The world it runs on is described in world.md.

The job

A clinic group loses patients in the gaps between systems: a result comes back abnormal and nobody opens it, a referral is sent and never booked, a clinician rings in sick with twelve people on the list, a procedure is two days away and the consent form was never signed. None of these is clinical judgement. Each is a follow-up that a person would do in a minute if they knew it was waiting.

Rounds is the operator that knows. It reads the clinic group's diary, results inbox, referrals, discharge notices and paperwork on a schedule, finds what has slipped, and does the administrative part itself when its written authority allows. Anything clinical, and anything beyond that authority, goes to a named person with the evidence attached.

The loop

Every tick of the clock, the operator runs one pass:

detect  →  dedupe  →  propose  →  decide  →  execute | queue | decline  →  record
  1. Detect. Each kind of problem is a definition in the dictionary: a named, versioned SQL query with an owner and tests. The detectors run only those definitions, never private SQL, so the operator acts on exactly what the group signed off. The policy says how often each one runs: the diary every tick (a sick clinician, a run of late cancellations, a double booking), results and referrals hourly, authorisations once a day at 07:00.
  2. Dedupe. The same problem on the same thing is handled once per fifteen minutes. A problem a person already turned down or undid is left alone.
  3. Propose. A worker turns each new incident into a proposal: one action, its arguments, and a reason. For most kinds there is only one sensible action, so a fixed rule fills it in and no model is asked. Where the runbook offers a real choice (move a double-booked appointment to a free room, or offer the patient a new slot), a language model can be asked. The model is optional: without one, the rules decide and the record says so.
  4. Decide. The controller checks every proposal against policy.yaml. It is separate from the model and does not trust it: the action must be listed, allowed for this kind of problem, aimed at the record the evidence names, inside its cooldown and inside the clinic's and the group's budgets. The answer is a tier.
  5. Act or ask. Tier 0 runs. Tier 1 runs and tells the clinic lead. Tier 2 goes to the sign-off queue for the person the policy names. Tier 3 is refused, whoever asks. Anything not listed is tier 3.
  6. Record. Every decision, including a refusal, is a row in the action record.

What it may do

The policy is the operator's written authority. It is a short YAML file owned by the medical director and the head of operations, and the controller reads it on every decision.

TierMeaningExamples
0Just do itoffer freed slots to the waitlist; send a booking offer or reminder; request a missing consent form; ask the prescriber to renew an authorisation; re-file a result whose label and order agree
1Do it and tellmove a double-booked appointment to a free room; move a sick clinician's list to colleagues
2Ask a personhand an unacknowledged abnormal result to the on-call doctor; cancel a clinic; merge two patient records
3Nevermedication, diagnosis, interpreting a result, deleting a record

Budgets keep a fault from turning into a flood: at most ten automatic actions at one clinic in any hour, thirty across the group in any minute, and a separate budget for the morning paperwork run so it never eats the clinic day's allowance.

Each action is named after the clinic system's FHIR-style call it stands for, so a record row reads like PATCH /Appointment/7612044 room=231 or POST /Flag + POST /Communication (on-call doctor, result 3228466). Nothing is sent anywhere: the line is the label a real adapter would act on.

The action record

The record is append-only. A row holds:

A status change never edits a row: a sign-off, a refusal or an undo is a new row pointing at the old one. Undo runs the stored rollback against the before-snapshot, and restores a row only if nobody has changed it since.

People in the loop

Tier 2 items wait in the sign-off queue. In the recorded runs, scripted synthetic staff answer it: an on-call doctor, a lab lead, a records lead, an operations manager and clinic leads, each with a response time and rules written in humans.yaml. They sign off when the evidence holds and turn items down when it does not (a namesake is not a duplicate; a list that should have been moved two hours ago is past saving). Their answers are ordinary record rows, labelled as scripted. On the live screen, the visitor can sign off or turn down an item in their place.

One dictionary

The detectors, the operator and the Ask screen share one dictionary: ten detector definitions and six words the group uses every day (no-show, late cancellation, abnormal result, acknowledged, overdue follow-up, active patient). Five of those words have two valid meanings in the group. A no-show for operations is a patient who did not arrive; for the health-fund contract it is also a cancellation at short notice, because the slot cannot be reused. Ask never picks one: it shows both, each with its owner, version and SQL. Changing a rule value (say, consent needed 96 hours ahead rather than

  1. can be previewed against the data before anyone commits it.

How it is measured

The world generator plants every problem and writes an answer key, incidents_truth, that nothing in the operator reads. After a replay, each finding is matched to the key by kind, subject and time. The accuracy screen shows, per detector, precision (how many findings were real) and recall (how many planted problems were found), plus the share handled without a person, actions undone, time to resolve, and how many decisions the rules made versus the model. The weakest detector is named on the screen, never hidden.

On the seed 23 hold-out (tuned on seeds 7 and 11 only): 143 planted problems in the replayed week, precision 92%, recall 97%, 62% handled without a person, four undone by staff. The weakest are the duplicate-record and misfiled-result detectors, at 67% precision each. The command and the full table are in the README.

The screens

Every number on a screen is read from the database or from the replay report written by the replay script.

Where the pieces live

PieceWhere
World generator and answer keyrounds/world/
Dictionary and its definitionsrounds/dictionary/, rounds/dictionary/definitions/*.yaml
Detectors, workers, controller, runnerrounds/agent/
Policy and scripted staffrounds/agent/policy.yaml, rounds/agent/humans.yaml
Tools and their undorounds/agent/tools/
Action recordrounds/ledger/
Scoringrounds/recal/
Askrounds/ask/
Replayscripts/replay_window.py
Screensapp/