diff --git a/docs/roadmap.md b/docs/roadmap.md index 03a4945..51e7206 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -76,7 +76,7 @@ Nothing in Phase A starts before every item is done. | S5 WhatsApp | WAHA (GOWS) with linked numbers, throttling, opt-in, reverse verification; fake WAHA for automated tests plus one manual day on two owner numbers (OD-45) ([spec](specs/spikes/0.3-s5-whatsapp.md), approved) | ADR-0036 amending ADR-0016/0017; OD-12 (stays open), OD-45, OD-46; planned as 0.3-S5a to 0.3-S5c (owner, 2026-11-17; ADR-0032 budget, manual day in its own slice) | | S6 Voice | Listening test: Azure ar-SY vs Google vs SILMA with 5 receptionists; kiosk autoplay on cheap Android TV boxes | ADR-0020, OD-11 | | S7 Push | FCM delivery on common Android phones in Aleppo and Azaz | ADR-0017 | -| S8 Charts | Interactive prototypes of odontogram, perio entry and skeleton chart, designed in Claude Design instead of Figma (OD-47) and tested as a static build with 3 dentists and 2 orthopedic surgeons ([spec](specs/spikes/0.3-s8-charts.md), approved) | dental, orthopedics docs; OD-19 and OD-20 (input only) | +| S8 Charts | Interactive prototypes of odontogram, perio entry and skeleton chart, designed in Claude Design instead of Figma (OD-47) and tested as a static build with 3 dentists and 2 orthopedic surgeons ([spec](specs/spikes/0.3-s8-charts.md), approved) | dental, orthopedics docs; OD-19 and OD-20 (input only); planned as 0.3-S8a to 0.3-S8d (owner, 2026-11-17; ADR-0032 budget; the owner's design pick and the doctor sessions sit between slices) | ## Phase 0.3 slices @@ -94,6 +94,10 @@ Nothing in Phase A starts before every item is done. | 0.3-S5a | WhatsApp spike, part 1: pinned WAHA (GOWS, PostgreSQL session storage, API key, HMAC webhooks; platform and clinic containers, no session started); fake WAHA with fault injection and OpenAPI parity against the pinned image; `sendWhatsApp` with allowlist, opt-in/opt-out, pg-boss per-session pacing (gap, hourly cap, quiet hours, variants), at-most-once sends, circuit breaker and fallbacks, health job, acks (manual CI `s5-whatsapp`) ([slice](slices/0.3-s5a-whatsapp-stack-and-sending.md)); criteria 1–8; ~3,900 lines | T0 | Planned | | 0.3-S5b | WhatsApp spike, part 2: reverse WhatsApp verification (HMAC-keyed codes, device-bound nonces with a device secret, rate limits, platform replies only on success), tenant and role separation by container and session, manual-run admin page, paced-batch script, fixture capture and scrub, owner checklist ([slice](slices/0.3-s5b-whatsapp-verification-and-tooling.md)); criteria 9–11 (tooling); after 0.3-S5a; ~2,300 lines | T0 | Planned | | 0.3-S5c | WhatsApp spike, part 3: the owner's one-day run on two dedicated numbers (OD-45), WAHA log check, fixture replay against the fake and real signing, measurements, report and ADR-0036 amending ADR-0016/0017 ([slice](slices/0.3-s5c-whatsapp-manual-day-and-result.md)); criteria 1–2 (real evidence), 7, 11–13; after 0.3-S5b; ~1,100 lines | T0 | Planned | +| 0.3-S8a | Charts spike, part 1: two design directions per chart as live Arabic RTL artboards in Claude Design with the owner's pick; pure chart rules (FDI order, surface aliases, layers, bridge group, CAL, perio path, sites and side rule, pain marks), the eleven scripted tasks, scorer, session-log schema and pass-mark function ([slice](slices/0.3-s8a-charts-design-and-rules.md)); criteria 1, 4–6 (rules), 8–9, 11 (logic); ~2,100 lines | T1 | Planned | +| 0.3-S8b | Charts spike, part 2: static React + Vite test shell (participant code, task runner, moderator marks, log export and wipe), odontogram with two palettes, surface picker, bridge wizard and undo, tasks D1–D4; Playwright on laptop and tablet viewports with the network blocked; manual CI `s8-charts` ([slice](slices/0.3-s8b-charts-shell-and-odontogram.md)); criteria 2–4, 7–9 (odontogram); after 0.3-S8a; ~3,200 lines | T1 | Planned | +| 0.3-S8c | Charts spike, part 3: six-site perio entry (keyboard and on-screen keypad), skeleton chart with zoom panels, side chips and pain drawing, tasks D5, D6, O1–O5; printed perio sheet, moderator script, serving to the tablet with the network off, owner dry run ([slice](slices/0.3-s8c-charts-perio-skeleton-and-session-kit.md)); criteria 2, 3, 5–8, 10 (script); after 0.3-S8b; ~3,700 lines | T1 | Planned | +| 0.3-S8d | Charts spike, part 4: the owner's five doctor sessions, anonymised logs, tables recomputed by a script, one revision round if a chart misses 80%, report, dental and orthopedics doc updates ([slice](slices/0.3-s8d-charts-sessions-and-result.md)); criteria 10–13; after 0.3-S8c and the sessions; ~1,200 lines (+ up to ~800 for a revision) | T1 | Planned | ## Phase A slices diff --git a/docs/slices/0.3-s8a-charts-design-and-rules.md b/docs/slices/0.3-s8a-charts-design-and-rules.md new file mode 100644 index 0000000..6586e51 --- /dev/null +++ b/docs/slices/0.3-s8a-charts-design-and-rules.md @@ -0,0 +1,52 @@ +# 0.3-S8a Charts spike: design directions in Claude Design, chart rules, task scoring + +Status: Planned (owner approved the plan, 2026-11-17) · Tier: T1 (clinical chart rules: tooth numbering, surfaces, laterality; throwaway code, no backend, no patient data) · Branch: `chore/0.3-s8a-charts-design-and-rules` +Spec: [0.3-S8 Charts](../specs/spikes/0.3-s8-charts.md) criteria 1, 4–6 (rules), 8–9 (task definitions, scoring, log schema), 11 (pass-mark arithmetic) · Requirements: DEN-01 (permanent only), DEN-05, DEN-06, DEN-07, DEN-08 (subset), DEN-09, DEN-11 (undo only), DEN-18 (PD, GM, CAL, BOP), DEN-19 (auto-advance, thresholds), ORT-02, ORT-03, ORT-05 · Decisions: ADR-0011 (unchanged), ADR-0023, ADR-0026, OD-19 and OD-20 (stay open), OD-31, OD-47 + +The spike is split in four by the ~4,000-line budget of [ADR-0032](../adr/0032-slice-size-budget-4000-lines.md) and by the two points where the owner's time is needed (the design pick, the doctor sessions): this slice holds the design exploration and everything that does not depend on the chosen direction; [0.3-S8b](0.3-s8b-charts-shell-and-odontogram.md) builds the test shell and the odontogram; [0.3-S8c](0.3-s8c-charts-perio-skeleton-and-session-kit.md) adds perio entry, the skeleton chart and the session kit; [0.3-S8d](0.3-s8d-charts-sessions-and-result.md) holds the sessions, the revision round and the report. Built in three checkpoints (A–C); A ends with the owner's pick. + +## Goal +The owner compares two live Arabic RTL design directions per chart in one Claude Design project and picks one each. The rules the three charts must obey, the eleven scripted tasks with their expected final states, the scorer and the session-log schema exist as a tested pure TypeScript package, so the UI slices only draw and wire. + +## Choices made by this plan +- **Claude Design work is done by the session** through the app's design artifact tooling; the project stays private to the owner's account and holds designs only (no doctor or clinic names, synthetic patient only). If the session cannot create or edit the project, it writes the six prompts into this file and the owner runs them. No Figma file is created (OD-47). +- **What the two directions vary** (so the pick decides something): odontogram: where the "existing" and "planned" palettes sit (two fixed side panels vs one panel with a layer switch that recolours the whole toolbar) and how surfaces are picked (enlarged five-surface tooth vs surface chips); perio: full-arch grid vs focused tooth with an arch strip; skeleton: side chip proposed from the tapped side and confirmed vs always blank until chosen. Rules fixed by the spec (anatomical orientation, tooth first, Missing ≠ Extracted, mandatory chip) are the same in both. +- **Rules live in `spikes/s8-charts/rules`** (`@shifa-spike/s8-rules`), no DOM, no React: written to be lifted into Phase B and C (spec, verification contract). +- **Surfaces:** canonical {M, O, D, B, L}; display alias I for O on anteriors (13–23, 33–43), F for B on anteriors, P for L on upper teeth. V is out of scope (spec lists five). +- **Scoring is on final state only** (spec 8): a task's expected state is a set of chart items; extra items fail it. D5 passes with at most 3 wrong cells over depths, margins and bleeding together. Skeleton pain marks are scored by symptom type, kind, intensity and the set of body regions (with side) the mark starts and ends in, not by pixels. +- **Wrong-tooth and wrong-side counters:** an applied action on a tooth outside the task's expected teeth, or a committed side chip or level different from the expected one, counts once each, even when undone later. +- **Log schema has no free-text field:** every string is an enum or a fixed pattern (participant code `D1`–`D3`, `O1`–`O2`; experience band; current-software list with "other"); a test walks the schema and fails on an unconstrained string. Free comments stay in the moderator's notes (0.3-S8d). +- **Digits:** Western digits in every rule output and label (spec 3). + +## Layout +- `spikes/s8-charts/rules/src/`: `fdi.ts` (order, quadrants, display order with patient's right on the viewer's left), `surfaces.ts`, `chart.ts` (items, layers, statuses, reducer with undo, refusals), `bridge.ts`, `perio.ts` (CAL, thresholds, auto-advance path, skip missing), `sites.ts` (site catalogue, which sides apply, hand/foot/spine qualifiers), `pain.ts`, `tasks.ts` (D1–D6, O1–O5: Arabic prompt, seed state, expected state), `score.ts`, `log.ts` (schema, attempt record), `passmark.ts`, `perio-sheet.ts` (seeded exam for D5). +- `docs/spikes/s8-design/`: one PNG per direction, chart and size (binary, not counted). + +## Plan +1. Contracts, database, API, Flutter: none (static spike). +2. **A. Design exploration (criterion 1):** one Claude Design project, artboards at 1366×768 and 1280×800, `dir="rtl"`, two directions per chart, each showing the hardest state (bridge wizard open; perio mid-entry with a 4 mm+ site and a missing tooth; skeleton with a pending side chip and a radiating mark). Screenshots committed; project link, the owner's pick per chart and the reasons recorded under Evidence. The session continues with B while the owner reviews. +3. **B. Chart rules (criteria 4–6):** files above, tests first. +4. **C. Tasks, scoring, log, pass mark (criteria 8, 9, 11):** task definitions, scorer, log schema, pass-mark function (80% per chart; no task failed by more than half of its participants; assisted and not-attempted handling; early stop). +5. End-to-end: none here; `test:spike` (Vitest) is wired into the manual workflow in 0.3-S8b. + +## Tests written first +- `fdi.test.ts` (3, 4): display order 18→11, 21→28 over 48→41, 31→38; quadrant and arch of every tooth; anterior/posterior class. +- `surfaces.test.ts` (4): alias per tooth position, round trip alias → canonical. +- `chart.test.ts` (4): tooth first (action with no selection refused); finding on a missing or extracted tooth refused; Missing and Extracted are different items; existing and planned layers never mix; multi-select across the midline; undo restores the exact prior state. +- `bridge.test.ts` (4): 45–47 with 46 pontic is one linked group; missing abutment refused; undo removes the whole group. +- `perio.test.ts` (5): CAL = PD + GM table (recession positive, negative margin, two-digit depth); path visits 168 sites once in the fixed order and skips missing teeth; correction after advance; highlight at 4 and above. +- `sites.test.ts`, `pain.test.ts` (6): no selection is complete without a side; midline sites offer only midline; side change after selection; C1–S1 levels and L4–L5 as an interspace; PIP of the right middle finger is one unambiguous site; radiating mark across regions. +- `score.test.ts`, `log.test.ts`, `passmark.test.ts` (8, 9, 11): correct path of every task scores success; missing/extracted swapped, wrong side, wrong surface, wrong pontic score fail; D5 with 3 wrong cells passes and with 4 fails; schema has no free-text field; pass-mark worked examples, including an early stop. + +Estimated hand-written lines: ~2,100 (budget ~4,000). Rules ~1,100; tests ~900; package files and this file ~100. Checkpoints: A (owner pick), B ~1,200, C ~800. + +## Stopped at +Not started. + +## Evidence +- Claude Design project: pending (link, screenshots, pick per chart) +- `verify` (fast): pending +- Reviewer findings fixed: pending + +## Notes for the next session +- The owner's pick is needed before 0.3-S8b starts; nothing else in this slice waits for it. diff --git a/docs/slices/0.3-s8b-charts-shell-and-odontogram.md b/docs/slices/0.3-s8b-charts-shell-and-odontogram.md new file mode 100644 index 0000000..5548288 --- /dev/null +++ b/docs/slices/0.3-s8b-charts-shell-and-odontogram.md @@ -0,0 +1,51 @@ +# 0.3-S8b Charts spike: test shell, session log and the odontogram + +Status: Planned (owner approved the plan, 2026-11-17) · Tier: T1 (tooth numbering and surfaces on screen; throwaway code, no backend, no patient data) · Branch: `chore/0.3-s8b-charts-shell-and-odontogram` +Spec: [0.3-S8 Charts](../specs/spikes/0.3-s8-charts.md) criteria 2, 3 (odontogram), 4, 7 (odontogram), 8 (D1–D4, D6 first half), 9 · Requirements: DEN-01 (permanent only), DEN-02, DEN-03, DEN-04, DEN-05, DEN-06, DEN-07, DEN-08 (subset), DEN-09, DEN-11 (undo only), DEN-15 · Decisions: ADR-0011 (unchanged), ADR-0023, ADR-0026, OD-20 (stays open), OD-31, OD-47 +After [0.3-S8a](0.3-s8a-charts-design-and-rules.md) (needs the owner's design pick and `@shifa-spike/s8-rules`). Built in four checkpoints (A–D). + +## Goal +The owner opens one static page, enters a participant code, and the build walks a dentist through tasks D1–D4 on the odontogram in Arabic, scores each attempt and exports the session log. The same bundle runs on the tablet by touch and makes no request outside its own origin. + +## Choices made by this plan +- **Stack:** React 19 + Vite (the clinic web stack, ADR-0010), plain CSS with logical properties only, no router, no `packages/ui`, no tokens (both out of scope); Arabic strings in a local file (not `packages/i18n`). Vazirmatn (ADR-0034) is bundled as a local font file; nothing loads from a CDN. +- **Charts are not mirrored in RTL:** each chart sits in a `dir="ltr"` island with the patient's right on the viewer's left, and a fixed "يمين المريض / يسار المريض" caption; the page around it is `dir="rtl"`. +- **Tooth art is self-drawn:** eight SVG templates (incisor, canine, premolar, molar × upper, lower) with a buccal + root view and a five-surface occlusal view, kept in `web/src/assets/teeth/` with a `SOURCE.md`, written to be reused in Phase B. +- **State:** the reducer from `@shifa-spike/s8-rules`; the running session is kept in `localStorage` so a reload does not lose it, and is cleared when the log is exported (criterion 2: nothing stored after export; tested). +- **Moderator controls:** a small "مشرف" corner control (long-press on touch, `Ctrl+Shift+M` on the laptop) opens: mark attempt assisted, skip task, end session. It is outside the participant's task area and never needed to finish a task. +- **Two devices, one file per participant:** each device exports `-.json`; the report script in 0.3-S8d merges them into one file per participant. The tablet file is moved to the laptop by cable (the moderator script says how). +- **Statuses:** the seven seed items use the fixed colours of DEN-07 for "existing", "planned" and "condition"; the other statuses are not shown. +- **Timing:** duration runs from the moment the task text is dismissed to "انتهيت"; the two minutes of free exploration are a separate untimed screen. + +## Layout +- `spikes/s8-charts/web/` (`@shifa-spike/s8-web`): `src/shell/` (participant form, task runner, moderator panel, export, ratings), `src/odontogram/` (arch, tooth, surface picker, palettes, bridge wizard), `src/assets/teeth/`, `src/strings.ar.ts`, `src/style/`. +- `spikes/s8-charts/e2e/` (`@shifa-spike/s8-e2e`): Playwright, projects `laptop` (1366×768, mouse and keyboard) and `tablet` (1280×800, `hasTouch`), both against `vite preview` of the built bundle. +- `.github/workflows/s8-charts.yml`: `workflow_dispatch` only, `permissions: {}`, actions pinned by SHA like `s3-arabic-output.yml`; jobs `rules` (Vitest) and `e2e` (Playwright, screenshots uploaded); no secrets. + +## Plan +1. Contracts, database, API, Flutter: none. +2. **A. Shell (criteria 2, 8, 9):** participant form (code, specialty, experience band, current software; no free text), free-exploration screen, task runner (one task at a time, Arabic text, device recorded), scoring call, moderator panel, five rating questions, export and wipe; a strict Content-Security-Policy meta tag (`default-src 'self'`). +3. **B. Odontogram rendering (criteria 3, 4):** both arches in FDI display order, anatomical and occlusal views, Missing (dimmed outline) and Extracted (crossed) symbols, status colours, selection (tap, drag, Ctrl/Shift, typing an FDI number). +4. **C. Actions (criterion 4):** "existing" and "planned" palettes as in the chosen direction, surface picker with I/F/P aliases, bridge wizard (abutments, pontic), undo, refusal messages for the edge cases. +5. **D. End-to-end and workflow (criteria 2, 3, 7, 8, 9):** suites below; `s8-charts.yml`. + +## Tests written first +- `e2e/tests/offline.spec.ts` (2): with every non-origin route aborted and the context offline after load, D1–D4 complete; any request outside the origin fails the test; `localStorage` and `sessionStorage` are empty after export. +- `e2e/tests/orientation.spec.ts` (3): under `dir="rtl"`, bounding boxes give 18 left of 11 left of 21 left of 28 and 48 … 38 below; Western digits on every tooth label; screenshots at both sizes. +- `e2e/tests/odontogram-tasks.spec.ts` (4, 8): the correct path of D1–D4 scores success; wrong paths score fail: Missing and Extracted swapped (D1), MO instead of MOD and wrong tooth 16 (D2), mesial instead of distal (D3), 45 as pontic (D4); action with no tooth selected and a finding on a missing tooth are refused; undo count and wrong-tooth count appear in the log. +- `e2e/tests/tablet.spec.ts` (7, 8): on the `tablet` project every interactive element in the shell and the odontogram measures at least 44×44 CSS px; D2 is finished with touch events only (first half of D6). +- `e2e/tests/log.spec.ts` (9): the exported file validates against the schema of 0.3-S8a; assisted mark, skip and early end are recorded; device is correct per project. + +Estimated hand-written lines: ~3,200 (budget ~4,000). Shell ~650; tooth art ~350; odontogram ~1,000; styles and strings ~300; Playwright ~800; workflow and package files ~100. Checkpoints: A ~900, B ~800, C ~700, D ~800. + +## Stopped at +Not started. + +## Evidence +- `verify` (fast): pending +- `s8-charts` workflow dispatch: pending +- Screenshots (both sizes): pending +- Reviewer findings fixed: pending + +## Notes for the next session +- Follow the direction the owner picked in 0.3-S8a (Evidence there); do not blend the two. diff --git a/docs/slices/0.3-s8c-charts-perio-skeleton-and-session-kit.md b/docs/slices/0.3-s8c-charts-perio-skeleton-and-session-kit.md new file mode 100644 index 0000000..7409136 --- /dev/null +++ b/docs/slices/0.3-s8c-charts-perio-skeleton-and-session-kit.md @@ -0,0 +1,51 @@ +# 0.3-S8c Charts spike: perio entry, skeleton chart and the session kit + +Status: Planned (owner approved the plan, 2026-11-17) · Tier: T1 (CAL sign convention, side and level on screen; throwaway code, no backend, no patient data) · Branch: `chore/0.3-s8c-charts-perio-skeleton-and-session-kit` +Spec: [0.3-S8 Charts](../specs/spikes/0.3-s8-charts.md) criteria 2 (whole build, tablet over the local network), 3 (perio, skeleton), 5, 6, 7, 8 (D5, D6, O1–O5), 10 (script only) · Requirements: DEN-15, DEN-18 (PD, GM, CAL, BOP), DEN-19 (auto-advance, keypad, thresholds), ORT-01, ORT-02, ORT-03, ORT-05 · Decisions: ADR-0023, ADR-0026, OD-17, OD-20 (stays open), OD-31, OD-47 +After [0.3-S8b](0.3-s8b-charts-shell-and-odontogram.md) (uses its shell, log and workflow). Built in four checkpoints (A–D); D ends with the owner's dry run on the real tablet. + +## Goal +A dentist enters a full six-site perio exam by keyboard or on-screen keypad, an orthopedic surgeon selects sites with an explicit side and draws pain on the skeleton, and the owner holds everything needed to run the five sessions: the fixed build, the printed perio sheet, the moderator script and a checked way to serve the build to the tablet with the network off. + +## Choices made by this plan +- **Perio path (one fixed path, spec 5):** 28 teeth, third molars not charted: upper buccal 17→27 (three sites per tooth in reading order), upper palatal 27→17, lower lingual 37→47, lower buccal 47→37. The session asks each dentist whether this is the path they expect (a rating question). +- **Entry:** one digit advances; `1` followed by a digit within 600 ms enters 10–19 (keyboard), and the keypad has a "10+" key; margins are entered in a second pass with a sign key; bleeding is a tap or the space bar on the current site. Backspace and tapping a cell correct a value without breaking the path. +- **Skeleton art:** public-domain Wikimedia anterior and posterior skeleton SVG if one passes a licence check recorded in `SOURCE.md` (file, author, licence, URL, retrieval date, edits); otherwise self-drawn. Hand, foot and spine panels are self-drawn schematics. The vendored file is marked `linguist-generated`; hit regions are hand-written and keyed by the site ids of `@shifa-spike/s8-rules`. +- **Side chips:** behaviour as in the direction picked in 0.3-S8a; in both, the selection is pending (dashed, not saved, "انتهيت" disabled) until a chip is chosen, midline sites offer only "خط المنتصف", and the anterior/posterior captions name the patient's right and left. +- **Pain marks:** SVG pointer strokes; point = tap, radiating = drag; six symptom types by colour and pattern (never colour alone); intensity 0–10 picked per mark; marks are kept per view and shown when switching views. +- **Serving to the tablet:** `pnpm --filter @shifa-spike/s8-web serve:lan` (`vite preview --host`) prints the address; the laptop and tablet share a network with no internet. Which network works on the owner's machines (a router without uplink, or a phone hotspot with mobile data off) is found in the dry run and written into the moderator script. +- **Moderator script is Arabic for speaking, English for instructions:** the sentences read to the doctor are in Arabic; it states that no real patient's findings may be entered, that consent is verbal and that only the participant code is recorded. + +## Layout +- `spikes/s8-charts/web/src/perio/` (grid, cell, keypad, path cursor), `src/skeleton/` (views, hit regions, zoom panels, side chips, pain layer), `src/assets/skeleton/` with `SOURCE.md`, `public/sheet.html` (printable D5 sheet from the seeded exam, Western digits). +- `docs/spikes/s8-moderator-script.md`, `docs/spikes/s8-moderator-notes-template.md`. + +## Plan +1. Contracts, database, API, Flutter: none. +2. **A. Perio entry (criterion 5):** grid for 28 teeth (missing teeth skipped), PD and GM rows with computed CAL, bleeding dots, red at 4 mm and above, keyboard entry, on-screen keypad on touch, D5 and the D6 sextant wired into the task runner; the printable sheet. +3. **B. Skeleton selection (criteria 3, 6):** anterior and posterior views, zoom panels for hand, foot and spine (C1–S1), side chips, O1–O3. +4. **C. Pain drawing (criterion 6):** marks, types, intensity, O4 and O5. +5. **D. Whole-build checks and session kit (criteria 2, 7, 10):** suites below over all eleven tasks; moderator script and notes template; `serve:lan`; owner dry run: every task once on the laptop and the tablet tasks on the real 10-inch tablet with the network off. + +## Tests written first +- `e2e/tests/perio.spec.ts` (5, 8): the correct path of D5 (168 depths from the sheet, margins and bleeding for one quadrant) scores success by keyboard; 3 wrong cells pass, 4 fail; a two-digit depth, a negative margin, a correction after auto-advance and a missing tooth in the path behave as specified; CAL cells equal PD + GM; cells at 4 and above are highlighted. +- `e2e/tests/skeleton.spec.ts` (3, 6, 8): the left knee's hit region is on the viewer's right in the anterior view and on the viewer's left in the posterior view; O1–O3 correct paths score success; right knee for O1, index finger or DIP for O2, L5–S1 for O3 score fail and raise the wrong-side or wrong-level count; a selection without a chip cannot be finished; a spine level offers no right or left; changing the side after selection. +- `e2e/tests/pain.spec.ts` (6, 8): O4 correct path scores success; right leg, anterior view, "sharp" instead of "burning" and intensity 5 score fail; a radiating mark across regions; marks survive a view switch. +- `e2e/tests/tablet.spec.ts` (7, extended): target sizes in perio and skeleton; D6 (D2 and one sextant of D5 by keypad) and O5 (O1 and O4) finished with touch events only. +- `e2e/tests/offline.spec.ts` (2, extended): all eleven tasks with the network blocked, no request outside the origin, storage empty after export. +- `e2e/tests/sheet.spec.ts`: the printed sheet's values equal the expected state of D5. + +Estimated hand-written lines: ~3,700 (budget ~4,000). Perio ~750; skeleton views, hit regions and panels ~850; pain layer ~450; styles and strings ~250; Playwright ~1,000; moderator script, notes template and sheet ~400. Checkpoints: A ~1,100, B ~1,000, C ~700, D ~900. If the estimate is overrun at checkpoint B, the session kit (script, notes template, dry run) moves to 0.3-S8d and the owner is told. + +## Stopped at +Not started. + +## Evidence +- `verify` (fast): pending +- `s8-charts` workflow dispatch: pending +- Owner dry run on the tablet (network off): pending +- Skeleton art source and licence: pending +- Reviewer findings fixed: pending + +## Notes for the next session +- The commit merged by this slice is the build the doctors use; the owner runs the sessions from it and records its hash in the notes template. diff --git a/docs/slices/0.3-s8d-charts-sessions-and-result.md b/docs/slices/0.3-s8d-charts-sessions-and-result.md new file mode 100644 index 0000000..b13594a --- /dev/null +++ b/docs/slices/0.3-s8d-charts-sessions-and-result.md @@ -0,0 +1,40 @@ +# 0.3-S8d Charts spike: doctor sessions, revision round, report + +Status: Planned (owner approved the plan, 2026-11-17) · Tier: T1 (confirms or changes clinical chart rules in the dental and orthopedics domain docs; real doctors take part, identified only by a code) · Branch: `chore/0.3-s8d-charts-sessions-and-result` +Spec: [0.3-S8 Charts](../specs/spikes/0.3-s8-charts.md) criteria 10–13 · Requirements: DEN-03, DEN-04, DEN-05, DEN-09, DEN-15, DEN-19, ORT-01, ORT-02, ORT-03, ORT-05 (confirmed or changed) · Decisions: ADR-0011 (unchanged), ADR-0023, ADR-0026, OD-17, OD-19 and OD-20 (input only, stay open), OD-47 +After [0.3-S8c](0.3-s8c-charts-perio-skeleton-and-session-kit.md). The session starts when the owner has the exported logs and moderator notes of the five sessions, so no branch waits for doctors' calendars. Built in three checkpoints (A–C); B exists only if a chart misses the pass mark. + +## Goal +The owner reads one report that says, with numbers recomputed from the committed logs, which chart rules five local doctors confirmed, which must change and what Phase B and C must build, and whether Claude Design should also replace Figma for the design system. + +## Choices made by this plan +- **Before the session (owner):** five in-person sessions from `docs/spikes/s8-moderator-script.md` on the build merged by 0.3-S8c: 3 dentists (about 45 minutes), 2 orthopedic surgeons (about 25 minutes); one exported file per device and the filled notes template per participant. +- **What enters the repository:** `docs/spikes/s8-logs/.json` (the per-device exports merged by the script) and `docs/spikes/s8-logs/-notes.md` (comments rewritten by the owner without names, clinics, places or anything that identifies a doctor; ADR-0026). A test refuses a log that fails the schema or a notes file with a phone-like digit run. +- **Numbers come from a script, never by hand:** `pnpm --filter @shifa-spike/s8-rules report docs/spikes/s8-logs` prints the per-task and per-chart tables (attempts, unassisted successes, assisted, not attempted, median and range of duration, undo, wrong-tooth and wrong-side counts, keyboard vs keypad for perio) with the pass-mark function of 0.3-S8a; the report embeds its output between markers and a test fails when they differ. +- **Revision round (criterion 12) stays in this slice:** a chart that misses gets one design revision (in the Claude Design project first, then in `spikes/s8-charts/web`), pushed on this branch; the owner retests its failed tasks with at least two participants (new ones where possible; repeats named) on that commit, and the retest logs are committed as `-r2.json`. A second miss is reported as a failure and carried to Phase B or C in the roadmap. If the revision would exceed about 800 lines, it becomes its own slice and the owner is told. +- **Five participants are a small sample:** the report gives counts, not percentages alone, and says so wherever a conclusion rests on one or two people. + +## Plan +1. Contracts, database, API, web, Flutter: none unless checkpoint B runs. +2. **A. Logs and numbers (criteria 9–11):** merge and validate the exports, commit logs and notes, report script and its tests, first tables; decide per chart: pass, or revision. +3. **B. Revision and retest (criterion 12, conditional):** revision of the failed chart, its Playwright suites kept green, owner retest, retest logs. +4. **C. Report and docs (criterion 13):** `docs/spikes/s8-charts.md` with one section per spec question (tooth-first, two palettes and Missing/Extracted against the 43% baseline; the bridge wizard; perio time by keyboard and keypad and the expected path; wrong side or level and the side chip; touch on the tablet; Arabic terms doctors use for surfaces, statuses, symptom types and sides; what doctors said about digits, as input to OD-20), the build commit(s), limits of the sample, and the advice on Claude Design vs Figma for the design system (a change needs a new ADR superseding the Figma line of ADR-0011 and closes OD-19; this slice writes no such ADR). `docs/domain/dental.md` and `docs/domain/orthopedics.md` get the confirmed and changed rules and their verification notes; `docs/open-decisions.md` gets the evidence under OD-19 and OD-20; roadmap and the four slice files updated. + +## Tests written first +- `rules/test/report.test.ts` (10–12): fixture logs with known outcomes give the expected tables; assisted attempts and early stops are counted as specified; a retest file replaces only the retested tasks and names repeat participants; merging two device files keeps every attempt once. +- `rules/test/committed-logs.test.ts` (9, 13): every file in `docs/spikes/s8-logs/` validates against the schema; participant codes are within `D1`–`D3`, `O1`–`O2` (plus retest codes); notes files hold no digit run of 8 or more; the tables embedded in the report equal the script's output. Runs in the `rules` job of the `s8-charts` workflow. + +Estimated hand-written lines: ~1,200 without a revision (budget ~4,000). Report script ~250; tests and fixtures ~250; report ~400; domain docs, open decisions, roadmap and slice files ~300. A revision adds up to ~800. + +## Stopped at +Not started. + +## Evidence +- Five session logs and notes: pending (owner) +- Report tables recomputed from the logs: pending +- `verify` (fast): pending +- `s8-charts` workflow dispatch: pending +- Reviewer check of the report against the logs: pending + +## Notes for the next session +- Agree the session dates with the owner at the end of 0.3-S8c; this slice needs all five participants' files (or a recorded early stop) before it starts.