Make AI suggestions visibly provisional and correction-first (#13) #69

2026-10-08T08:12:47Z

rockachopa commented

2026-10-08 08:12:47 +00:00

Closes #13

Outcome

AI suggestions are now a distinct, provisional state everywhere they appear, and correcting one clears the AI-confirmed state without losing anything the user entered.

What changed

src/suggestion.js (new): provenance state machine for a log entry's visual fields — pending → confirmed → corrected, plus manual when no suggestion was in play. It also owns the visible and screen-reader copy for each state.
app.js: the scan result renders as provisional (data-provenance="pending", confidence badge retained, "nothing is saved until you confirm it"); confirming is an explicit act; tapping a different type or changing the colour clears the AI-affirmed state, records the correction, and keeps every user field (urgency, discomfort, note, photo) intact. Step 2's note now reports the correction instead of silently dropping the suggestion.
styles.css: dashed/neutral provisional styling, teal confirmed styling, amber corrected styling so the three states never look alike.
tests/suggestion.test.js (new): state machine and accessibility copy.
tests/provisional-suggestion.acceptance.mjs (new): browser acceptance with screenshots.
scripts/record_release_demo.mjs: the demo now reviews → confirms → corrects the suggestion on camera, with touch indicators and captions, then shows the corrected value surviving in the retained draft.
.gitea/workflows/quality.yml, scripts/build_release.py, package.json: the new unit file and browser acceptance are gated in CI, the release builder, and the manifest (provisional_suggestion_state).

Acceptance criteria

Suggested and confirmed states are visually and semantically distinct — data-provenance + AI SUGGESTION (dashed) vs AI PREFILLED (teal) vs CORRECTED BY YOU (amber), each with its own copy.
Changing a suggestion clears AI-confirmed state without losing user context — affirmed flips to false, the suggestion is retained as context, and urgency/note/photo/colour survive the correction.
Screen-reader copy communicates confidence and user control — e.g. "AI suggestion with 83 percent confidence… not saved until you confirm it"; "You confirmed the AI suggestion with 83 percent confidence… You can still change any of it"; "You changed the AI suggestion. It suggested Type 4, brown; you chose Type 2".

Evidence (all run from a clean clone of this branch, commit `5aee743`)

npm test → 92 pass / 0 fail
npm run test:ui|test:photo|test:mobile-capture|test:sleek|test:manual-fallback|test:provisional → all pass
python3 tests/staging-deploy.test.py -v → 20 tests OK
npm run check:syntax → pass; npm audit --audit-level=high → 0 vulnerabilities
node scripts/record_release_demo.mjs → 51s webm; OCR of extracted frames confirms the video visibly shows AI SUGGESTION · 83% CONFIDENCE + "provisional", "…and you confirmed it", and CORRECTED BY YOU / Type 2 · brown with the caption "Change a suggested value and Timmy clears the AI-confirmed state".
Screenshots: artifacts/provisional-suggestion-{pending,confirmed,corrected}-mobile.png

Privacy / safety boundary

No change to the product boundary. The suggestion still covers only visible Bristol form, broad colour, and image quality; urgency, discomfort, symptoms, and notes remain user-entered, deterministic symptom escalation is untouched, and this PR adds no inference, no new upload path, and no model or image data. All demo and test data is the existing synthetic fixture — no real medical image is in this branch, and no secret or generated artifact is included.

Demo path changed

scripts/record_release_demo.mjs — the feature is exercised live (mocked synthetic vision response) so tomorrow's release video covers this exact change. Infrastructure-only steps: none in this PR.

Closes #13 ## Outcome AI suggestions are now a distinct, provisional state everywhere they appear, and correcting one clears the AI-confirmed state without losing anything the user entered. ## What changed - `src/suggestion.js` (new): provenance state machine for a log entry's visual fields — `pending` → `confirmed` → `corrected`, plus `manual` when no suggestion was in play. It also owns the visible and screen-reader copy for each state. - `app.js`: the scan result renders as provisional (`data-provenance="pending"`, confidence badge retained, "nothing is saved until you confirm it"); confirming is an explicit act; tapping a different type or changing the colour clears the AI-affirmed state, records the correction, and keeps every user field (urgency, discomfort, note, photo) intact. Step 2's note now reports the correction instead of silently dropping the suggestion. - `styles.css`: dashed/neutral provisional styling, teal confirmed styling, amber corrected styling so the three states never look alike. - `tests/suggestion.test.js` (new): state machine and accessibility copy. - `tests/provisional-suggestion.acceptance.mjs` (new): browser acceptance with screenshots. - `scripts/record_release_demo.mjs`: the demo now reviews → confirms → corrects the suggestion on camera, with touch indicators and captions, then shows the corrected value surviving in the retained draft. - `.gitea/workflows/quality.yml`, `scripts/build_release.py`, `package.json`: the new unit file and browser acceptance are gated in CI, the release builder, and the manifest (`provisional_suggestion_state`). ## Acceptance criteria - [x] Suggested and confirmed states are visually and semantically distinct — `data-provenance` + `AI SUGGESTION` (dashed) vs `AI PREFILLED` (teal) vs `CORRECTED BY YOU` (amber), each with its own copy. - [x] Changing a suggestion clears AI-confirmed state without losing user context — `affirmed` flips to false, the suggestion is retained as context, and urgency/note/photo/colour survive the correction. - [x] Screen-reader copy communicates confidence and user control — e.g. "AI suggestion with 83 percent confidence… not saved until you confirm it"; "You confirmed the AI suggestion with 83 percent confidence… You can still change any of it"; "You changed the AI suggestion. It suggested Type 4, brown; you chose Type 2". ## Evidence (all run from a clean clone of this branch, commit 5aee743) - `npm test` → 92 pass / 0 fail - `npm run test:ui|test:photo|test:mobile-capture|test:sleek|test:manual-fallback|test:provisional` → all pass - `python3 tests/staging-deploy.test.py -v` → 20 tests OK - `npm run check:syntax` → pass; `npm audit --audit-level=high` → 0 vulnerabilities - `node scripts/record_release_demo.mjs` → 51s webm; OCR of extracted frames confirms the video visibly shows `AI SUGGESTION · 83% CONFIDENCE` + "provisional", "…and you confirmed it", and `CORRECTED BY YOU / Type 2 · brown` with the caption "Change a suggested value and Timmy clears the AI-confirmed state". - Screenshots: `artifacts/provisional-suggestion-{pending,confirmed,corrected}-mobile.png` ## Privacy / safety boundary No change to the product boundary. The suggestion still covers only visible Bristol form, broad colour, and image quality; urgency, discomfort, symptoms, and notes remain user-entered, deterministic symptom escalation is untouched, and this PR adds no inference, no new upload path, and no model or image data. All demo and test data is the existing synthetic fixture — no real medical image is in this branch, and no secret or generated artifact is included. ## Demo path changed `scripts/record_release_demo.mjs` — the feature is exercised live (mocked synthetic vision response) so tomorrow's release video covers this exact change. Infrastructure-only steps: none in this PR.

rockachopa added 1 commit 2026-10-08 08:12:48 +00:00

feat: make AI suggestions visibly provisional and correction-first (#13 )

Quality gates / quality (pull_request) Successful in 1m45s

Details

5aee7436f2

Suggested, confirmed, and corrected AI states are now distinct in the log
sheet, and correcting a suggested value clears the AI-confirmed state while
keeping every user-entered field. Screen-reader copy states the AI confidence
and who is in control.

- src/suggestion.js: provenance state machine (pending/confirmed/corrected/manual)
- app.js: renders provenance on the scan result and log steps, tracks corrections
- tests/suggestion.test.js: unit coverage for the state machine and a11y copy
- tests/provisional-suggestion.acceptance.mjs: browser acceptance + screenshots
- record_release_demo.mjs: demo now reviews, confirms, and corrects the suggestion
- CI, release builder, and release notes gate the new contract

rockachopa closed this pull request

2026-10-08 12:04:02 +00:00

Pull request closed

Please reopen this pull request to perform a merge.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: stackchain/timmy-talking-turd#69