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
- 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.
- 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.
- 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.
- 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. - 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.
- 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.
| Tier | Meaning | Examples |
|---|---|---|
| 0 | Just do it | offer 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 |
| 1 | Do it and tell | move a double-booked appointment to a free room; move a sick clinician's list to colleagues |
| 2 | Ask a person | hand an unacknowledged abnormal result to the on-call doctor; cancel a clinic; merge two patient records |
| 3 | Never | medication, 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:
- the incident and the evidence rows the definition returned;
- the definition and its version;
- whether rules or the model proposed, and the reason given;
- the controller's decision and its plain-English reason;
- the call, the tier and the status;
- who signed it off, if anyone;
- the before and after snapshot of what changed, and the function that restores the before.
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
- 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
- Day board. The main screen. Clinics of one region as columns, the clinic day as rows, every booking as a block coloured by how it stands at that moment (booked, arrived, seen, no-show, cancelled late, filled from the waitlist). Across the top runs the results lane: every abnormal result still waiting for a clinician, with its age against the rule, and the specimens still in the lab. The operator's receipts land on the board in the clinic and hour they happened, and a rail on the right lists them for the whole group.
- Play mode. A clock over the busiest window, Monday 08:00 to 13:00, at 20, 60 or 120 times real speed. On a recorded run, the board replays every booking, result and receipt at its own time. On a fresh world, Play starts the operator itself and its actions land as it takes them. The timeline under the clock marks every action and moves the clock when clicked.
- Action record, Sign-off, Accuracy, Definitions, Ask, this page, and Known gaps.
Every number on a screen is read from the database or from the replay report written by the replay script.
Where the pieces live
| Piece | Where |
|---|---|
| World generator and answer key | rounds/world/ |
| Dictionary and its definitions | rounds/dictionary/, rounds/dictionary/definitions/*.yaml |
| Detectors, workers, controller, runner | rounds/agent/ |
| Policy and scripted staff | rounds/agent/policy.yaml, rounds/agent/humans.yaml |
| Tools and their undo | rounds/agent/tools/ |
| Action record | rounds/ledger/ |
| Scoring | rounds/recal/ |
| Ask | rounds/ask/ |
| Replay | scripts/replay_window.py |
| Screens | app/ |