Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
docs(0.3-s8): plan the charts spike as slices 0.3-S8a to 0.3-S8d
Split by the ADR-0032 budget and by the two points that need the owner:
the design pick (end of S8a) and the doctor sessions (before S8d).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
  • Loading branch information
HussienALfajer and claude committed Nov 16, 2026
commit c66c53e7ed9913adb9302c31ee1df854a97a45a9
6 changes: 5 additions & 1 deletion docs/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down
52 changes: 52 additions & 0 deletions docs/slices/0.3-s8a-charts-design-and-rules.md
Original file line number Diff line number Diff line change
@@ -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.
51 changes: 51 additions & 0 deletions docs/slices/0.3-s8b-charts-shell-and-odontogram.md
Original file line number Diff line number Diff line change
@@ -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 `<code>-<device>.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.
Loading