|
| 1 | +# 0.3-S8a Charts spike: design directions in Claude Design, chart rules, task scoring |
| 2 | + |
| 3 | +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` |
| 4 | +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 |
| 5 | + |
| 6 | +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. |
| 7 | + |
| 8 | +## Goal |
| 9 | +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. |
| 10 | + |
| 11 | +## Choices made by this plan |
| 12 | +- **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). |
| 13 | +- **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. |
| 14 | +- **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). |
| 15 | +- **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). |
| 16 | +- **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. |
| 17 | +- **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. |
| 18 | +- **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). |
| 19 | +- **Digits:** Western digits in every rule output and label (spec 3). |
| 20 | + |
| 21 | +## Layout |
| 22 | +- `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). |
| 23 | +- `docs/spikes/s8-design/`: one PNG per direction, chart and size (binary, not counted). |
| 24 | + |
| 25 | +## Plan |
| 26 | +1. Contracts, database, API, Flutter: none (static spike). |
| 27 | +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. |
| 28 | +3. **B. Chart rules (criteria 4–6):** files above, tests first. |
| 29 | +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). |
| 30 | +5. End-to-end: none here; `test:spike` (Vitest) is wired into the manual workflow in 0.3-S8b. |
| 31 | + |
| 32 | +## Tests written first |
| 33 | +- `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. |
| 34 | +- `surfaces.test.ts` (4): alias per tooth position, round trip alias → canonical. |
| 35 | +- `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. |
| 36 | +- `bridge.test.ts` (4): 45–47 with 46 pontic is one linked group; missing abutment refused; undo removes the whole group. |
| 37 | +- `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. |
| 38 | +- `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. |
| 39 | +- `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. |
| 40 | + |
| 41 | +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. |
| 42 | + |
| 43 | +## Stopped at |
| 44 | +Not started. |
| 45 | + |
| 46 | +## Evidence |
| 47 | +- Claude Design project: pending (link, screenshots, pick per chart) |
| 48 | +- `verify` (fast): pending |
| 49 | +- Reviewer findings fixed: pending |
| 50 | + |
| 51 | +## Notes for the next session |
| 52 | +- The owner's pick is needed before 0.3-S8b starts; nothing else in this slice waits for it. |
0 commit comments