diff --git a/data/repo-awareness-snapshot.json b/data/repo-awareness-snapshot.json index d17442835d..9be88a073c 100644 --- a/data/repo-awareness-snapshot.json +++ b/data/repo-awareness-snapshot.json @@ -1,8 +1,8 @@ { "version": "repo-awareness-snapshot-v1", "captured_revision": { - "sha": "9cc091d5b3034def48bbf5f41d27a0d5e3db652f", - "committed_at": "2026-08-27T04:53:21+00:00" + "sha": "5d848e0d24e4669a0fc41ef37aaab1f77ae5c323", + "committed_at": "2026-08-27T13:18:04+08:00" }, "routes": { "modes": [ @@ -3456,6 +3456,11 @@ "section": "root", "catalogued": true }, + { + "path": "docs/ward-flow-clinician-check.md", + "section": "root", + "catalogued": true + }, { "path": "docs/ward-flow-complete-ledger.md", "section": "root", @@ -3746,6 +3751,16 @@ "section": "root", "catalogued": false }, + { + "path": "docs/ward-flow-phase-6-7-decisions.md", + "section": "root", + "catalogued": true + }, + { + "path": "docs/ward-flow-phase-6-7-kickoff-prompt.md", + "section": "root", + "catalogued": true + }, { "path": "docs/ward-flow-phase-handoff.md", "section": "root", @@ -3847,8 +3862,8 @@ } ], "counts": { - "documents": 476, - "catalogued": 103, + "documents": 479, + "catalogued": 106, "uncatalogued": 373, "sections": 19 } diff --git a/docs/README.md b/docs/README.md index 7acf35c0ca..6098437cc7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -85,6 +85,9 @@ npm run docs:check-links - [continuous-integration.md](continuous-integration.md) — workflow concurrency keys, push exemption, and Guard 2 in-flight CI push guard - [testing.md](testing.md) — test execution, focused/live commands, Playwright ownership, flake policy - [development-speed-playbook.md](development-speed-playbook.md) — going faster without weakening any gate: arbiter, receipts, narrow selection, worktree reuse +- [ward-flow-clinician-check.md](ward-flow-clinician-check.md) — one-page plain-English check of the four-stage bed model, for a ward clinician +- [ward-flow-phase-6-7-decisions.md](ward-flow-phase-6-7-decisions.md) — owner decisions settled before Phases 6 and 7 are designed +- [ward-flow-phase-6-7-kickoff-prompt.md](ward-flow-phase-6-7-kickoff-prompt.md) — paste-in prompt to open the Phase 6 and 7 design conversation - [phone-chrome-physical-acceptance.md](phone-chrome-physical-acceptance.md) — labelled Safari and cold-launch PWA acceptance matrix - [productivity-workflows.md](productivity-workflows.md) — repo workflow planners (flightplan, triage, rag-lab, …) - [codex-review-protocol.md](codex-review-protocol.md) — shared review protocol for all review skills diff --git a/docs/ward-flow-clinician-check.md b/docs/ward-flow-clinician-check.md new file mode 100644 index 0000000000..921f8b3e85 --- /dev/null +++ b/docs/ward-flow-clinician-check.md @@ -0,0 +1,87 @@ +# How we've modelled a bed coming free — does this match reality? + +**One page. No software knowledge needed. Five minutes.** + +We're building a prototype that helps a bed coordinator see where there is a bed right now. It +holds no real patient information — everything in it is made up. Before we build the next part on +top of it, we want to know whether the way we've described a bed becoming free actually matches how +it works on a ward. + +**You are not being asked to check software.** You are being asked whether four words, and the +order they come in, describe something real. + +--- + +## What we assumed + +We assumed a bed becomes free by passing through four stages, in this order: + +| Stage | What we mean by it | +| ------------- | ------------------------------------------------------------------------------- | +| **Predicted** | Someone on the ward thinks this person will probably go home, and roughly when. | +| **Confirmed** | It is now decided. They are going. The bed will come free. | +| **Blocked** | It was going to happen, and something is now stopping it. | +| **Released** | The person has actually left. The bed is empty and can be filled. | + +Only the ward can move a bed between these stages. The bed coordinator can see them but cannot +change them — they can only ask a ward to update its numbers. + +We also assumed that a **predicted** bed is never counted as available. A coordinator looking for a +bed today sees only beds that are genuinely empty now, with predictions shown separately alongside. + +--- + +## The three things we think are most likely wrong + +**1. Can a bed be confirmed and blocked at the same time?** + +We've treated these as separate stages, so a bed is in one or the other. But in reality a discharge +might be decided and simultaneously stuck — the decision is made, transport isn't available. Is +"blocked" a stage that replaces "confirmed", or is it a flag that sits on top of it? + +**2. Is "predicted" one thing, or several?** + +We've used one word. A charge nurse might distinguish between "we're thinking about it on the ward +round", "the family have been told", and "we're waiting on one thing before we commit" — which +sound like quite different levels of confidence to plan against. + +We do offer two levels of confidence, "likely" and "possible", but only while a discharge is +predicted. Is that the right split, or the wrong axis entirely? + +**3. Does a bed ever go backwards?** + +We've assumed the four stages run one way. Does a confirmed discharge ever return to being merely +predicted — the decision is reversed, the person stays? If so, that needs building in. + +--- + +## Other things worth a moment + +- **We stop at the end of today.** Anything expected after this evening is deliberately left out of + every count, and the screen says how many were left out. We took the view that beyond roughly a + day, a discharge prediction is a guess. Is a day the right horizon, or too short? + +- **The board shows who confirmed a number and when** — as a role, never a person's name. Is + knowing "which ward said this, and how long ago" enough to trust a number, or would you need more? + +- **Beds on leave are counted separately** and never mixed into the available figure, because a bed + someone is coming back to is not a bed you can fill. + +--- + +## What we'd like back + +Nothing written. Just, in conversation: + +1. Do the four stages describe something you recognise? +2. Which of the three questions above has the wrong answer in our version? +3. Is there a stage we've missed entirely? + +**Changing this now is cheap.** Everything is invented data and nothing depends on it yet. The next +part of the prototype is built entirely from these numbers, so the cost of getting it wrong rises +sharply once that exists — which is why we're asking first. + +--- + +_This describes a prototype for thinking with. It is not clinical decision support, it contains no +real patient information, and it makes no statement about any legal requirement._ diff --git a/docs/ward-flow-phase-6-7-decisions.md b/docs/ward-flow-phase-6-7-decisions.md new file mode 100644 index 0000000000..2f08e85fc3 --- /dev/null +++ b/docs/ward-flow-phase-6-7-decisions.md @@ -0,0 +1,123 @@ +# Ward Flow Phases 6 and 7 — decisions taken before design + +**Recorded 2026-08-27.** These are the product owner's answers to the questions that had to be +settled before Phases 6 and 7 could be specified. They were given in conversation, and this file +exists so they survive it — the recurring failure in this project is a decision that lived only in +chat and was then re-derived, or contradicted, by a later session. + +Where this file and a later specification disagree, **the specification wins**, because it will +have been written with more detail in front of it. Where this file and someone's recollection +disagree, this file wins. + +Nothing here is built yet. This is the input to the design conversation, not its output. + +--- + +## Phase 6 — the morning page + +| # | Question | Decision | +| --- | ------------------------------------- | ----------------------------------------------------------------------------------- | +| 1 | Who is it for? | The **bed coordinator starting a shift**. Not the ward, not a manager. | +| 2 | The single headline number | **Beds available right now, across the whole service.** | +| 3 | Fixed moment or live? | **Fixed at the morning handover**, with a live view one click away. | +| 4 | Scope | **Whole service, grouped by hospital** — roll-up first, per-site detail underneath. | +| 12 | Fold in the sixty-second guided tour? | **Yes.** Defer "named moments on the demo clock" to a later phase. | + +The reasoning behind 3 is worth keeping: a page that stops moving can be printed, pinned up and +argued over. Since the entire point of Phase 6 is producing something to put in front of +colleagues, the version that holds still is the more useful one. + +--- + +## Phase 7 — the front door + +### What a referral may carry + +**Age band, sex, and whether a secure bed is needed — and nothing else.** No name, no date of +birth, no record number, no address, no diagnosis, no narrative history, no treatment, and no free +text anywhere. This extends rather than replaces the standing constraint that the prototype holds +no real patient information. + +### Bed categories — the owner's list, used verbatim + +These are **not one flat list of eight labels.** They are separate dimensions that combine, and the +owner said so explicitly: the legal-status pair cuts across the age categories, so any age category +may be either. + +| Dimension | Values | +| ---------------- | ------------------------------------------------ | +| **Age** | Older Adult · Adult · Youth | +| **Legal status** | Voluntary · Involuntary | +| **Sex** | Undesignated (default) · Female only · Male only | +| **Forensic** | Forensic · not forensic | + +A bed is therefore described by a combination — an _Adult, Involuntary, Forensic_ bed that is +undesignated for sex — rather than by picking one label from a list. + +**Both readings were confirmed by the owner on 2026-08-27**, and one of them corrected an +assumption that had been recorded wrongly: + +1. **Forensic is its own fourth dimension and combines with the others.** Confirmed as assumed. + An "Adult, Involuntary, Male-only, Forensic" bed is expressible. Forensic does not stand alone + or replace the other three. +2. **Most beds are undesignated for sex; some are female-only or male-only.** This **corrects** the + earlier assumption that every bed carries a designation. Undesignated is the normal case and + should be the default, not an exceptional value bolted on. + +### Why the sex dimension is a constraint, not an attribute + +This one behaves differently from the other three and the distinction matters for matching: + +- **Undesignated** places no restriction. Any patient may occupy the bed. +- **Female only** and **Male only** restrict who may occupy it. + +So sex-designation is a **property of the bed that constrains which referrals fit**, not a +description of an occupant. A matching rule that treats it as a value to compare for equality will +wrongly exclude every referral from every undesignated bed — which, since undesignated is the +majority case, would break matching almost entirely. Model it as "does this bed accept this +person", never as "does this bed's sex equal this person's sex". + +This is also why sex is one of the three permitted referral fields: without it, a referral cannot be +tested against a designated bed at all. + +### Legal status may be shown as a plain label + +Voluntary and Involuntary are part of how a bed is described, so the label is **in**. The absolute +constraint is unchanged and unaffected by this: **no figure, timeframe, threshold or duration from +the Mental Health Act may appear anywhere** — not in code, copy, comment, test or fixture. A label +saying which of the two applies is not a legal figure. If one is ever needed, stop and ask. + +### Referral sources + +**One referral type carrying a source label** — community, crisis service, police, ambulance, +inter-hospital transfer. Not five separate pathways. Split them later only if a real behavioural +difference appears; building five up front means maintaining five before we know whether they +differ. + +### Referral outcome + +A referral can be **accepted, declined with a reason chosen from a fixed list, or left queued**, and +the **coordinator** holds that decision. A referral board on which nobody can say no does not +reflect how any of this works, and a fixed reason list keeps free text out. + +--- + +## Sequencing + +1. **The clinician check comes first** — `docs/ward-flow-clinician-check.md`. It is the only + outstanding item that gets more expensive the longer it waits, because Phase 6 is built entirely + on the four-stage model and Phase 7 builds further on top. +2. **Then Phases 6 and 7 are designed in one conversation**, each still receiving its own written + specification. Only the conversation is shared. That is the roadmap's own instruction and the + reason is the fixed setup cost of a design conversation. + +--- + +## Still open + +- Everything the clinician check comes back with. + +Both bed-category readings were confirmed by the owner on 2026-08-27 and are no longer open. One of +them — sex designation — corrected an assumption recorded here wrongly, which is precisely the +reason assumptions are written down as assumptions rather than folded silently into a +specification. diff --git a/docs/ward-flow-phase-6-7-kickoff-prompt.md b/docs/ward-flow-phase-6-7-kickoff-prompt.md new file mode 100644 index 0000000000..dd9d124acd --- /dev/null +++ b/docs/ward-flow-phase-6-7-kickoff-prompt.md @@ -0,0 +1,101 @@ +# Ward Flow Phases 6 and 7 — kickoff prompt + +Paste the block below into a fresh session as its first message. It is deliberately self-sufficient: +the constraints are stated inline rather than only referenced, so they bind before the linked +documents are read. + +**This is a design conversation, not a build.** It produces two written specifications. Do not let +it start writing product code — the Phase 5 pattern was spec first, build second, and it worked. + +**Before pasting, check one thing:** has the clinician check +(`docs/ward-flow-clinician-check.md`) come back? If it has, say what it said. If it has not, say so +explicitly — the four-stage model is the single assumption most likely to be wrong, and Phase 6 is +built entirely from it. + +--- + +``` +Design Ward Flow Phases 6 and 7. This is a design conversation producing two written +specifications, not an implementation session. Do not write product code. + +READ THESE FIRST, IN THIS ORDER: + +1. docs/ward-flow-phase-6-7-decisions.md — the product owner's answers to every question that had + to be settled first. These are decided. Do not re-open them, and do not re-derive them. +2. docs/ward-flow-roadmap.md — direction, phase order, and the refusals that are already settled. +3. docs/superpowers/specs/2026-08-26-ward-flow-phase-5-bed-availability-design.md — the Phase 5 + spec, whose 14 decisions Phase 6 builds on directly. +4. docs/ward-flow-phase-5-handover.md — what was built and what is proven, by what evidence. +5. docs/ward-flow-complete-ledger.md §5d — what the screenshots caught, and what is still open. +6. docs/development-speed-playbook.md — how to work fast here without weakening any gate. +7. AGENTS.md and CLAUDE.md — repository rules. They override generic habits. + +WHAT PHASE 6 IS + +The morning page. One page for a bed coordinator starting a shift, built entirely from numbers +Phase 5 already produces. Fixed at the morning handover with a live view one click away. Whole +service, grouped by hospital. Headline number: beds available right now. It also carries a +sixty-second self-driving guided tour — a patient waiting, a coordinator finding a bed, a ward +confirming, the board updating. + +It is small on purpose. Its real output is something you can hand to a colleague as a link +instead of narrating over their shoulder. Finding out whether any of this is right is worth more +than the next feature. + +WHAT PHASE 7 IS + +The front door. Community referrals, intake from crisis services, police, ambulance and +inter-hospital transfers, matching to bed type, and the data-entry screens each contributor needs. +The bed-category model and the permitted referral fields are already decided — read them in the +decisions document and use them verbatim. + +CONSTRAINTS THAT OVERRIDE EVERYTHING + +1. Never invent a legal figure. Nothing from the Mental Health Act may be cited, paraphrased or + inferred — not in code, copy, comment, test or fixture. A plain Voluntary/Involuntary label is + permitted and is not a legal figure. If an actual figure is ever needed, stop and ask. +2. Synthetic data only. For a referral the permitted fields are age band, sex, and whether a secure + bed is needed — nothing else. No name, date of birth, record number, address, diagnosis, + history or treatment. Free text counts as data. +3. Local and offline checks only. Never run verify:release, any eval:* script, + check:supabase-project, test:live, or anything touching OpenAI, Supabase, hosted CI or a live + database. +4. The rule Phase 5 exists to hold, which Phase 6 must not break: nothing predicted, + confirmed-but-unreleased, or on leave is ever added into "available now". +5. Never force-push, git reset --hard, or discard either side of a diverged branch. Never delete a + worktree unasked. +6. Do not skip a gate, delete an assertion, loosen a test, or lower a tolerance. If a change would + reduce what can honestly be claimed, do not make it — say so instead. + +HOW TO WORK + +Check state before trusting any document's account of itself: `gh pr view --json state` first, +`git worktree list` before creating a worktree, and refresh a remote ref before reasoning from it. +Three times in one session on 2026-08-27, work was nearly redone that had already been done and +written down. docs/development-speed-playbook.md §1 records why. + +Produce each specification as its own file under docs/superpowers/specs/, following the Phase 5 +spec's shape: numbered decisions, each with its reasoning, and an explicit statement of what is +deliberately excluded. State plainly which decisions are assumptions that have not been validated. + +Ask me before designing anything that would need a fact neither of us has. +``` + +--- + +## The bed-category model, settled 2026-08-27 + +Both previously open questions were answered by the owner and are recorded in +`docs/ward-flow-phase-6-7-decisions.md`. The design conversation should treat them as decided: + +1. **Forensic is a fourth independent dimension** and combines with the other three. +2. **Most beds are undesignated for sex**; some are female-only or male-only. Undesignated is the + default and the majority case. + +The second one corrected an assumption that had been written down wrongly, so read the decisions +document rather than working from memory or from an older copy of this file. + +**One trap the design must not fall into.** Sex designation is a constraint on who may occupy a +bed, not an attribute to compare for equality. Matching "bed sex equals patient sex" excludes every +referral from every undesignated bed — the majority of them. The rule is "does this bed accept this +person".