Learn from Corrections

Spec for the Jot for iPhone and Jot for Windows agents. Shipped in Jot for Mac 1.23 (2026-09-29). Source of truth: jot/docs/vocabulary-learn-from-edits/design.md (Revision 2) and jot-shared 42e2428: VocabularyLearning.swift, DecoderVocabulary.swift, EditLearner.swift, CorrectionStore.swift, VocabularyGate.swift.

What the user gets. Correct a wrong word once, any way (edit the transcript, Add to Vocabulary, pick a suggestion, confirm the popup, type a "sounds like" in Settings), and the next dictation writes it. Every correction is saved once, visibly, as a "sounds like" on the term; delete it to undo. No hidden replace rules.

Verified end to end through the real Mac pipeline on the owner's 7 "Claude" recordings: before, "cloud"; after one correction, 7/7 "Claude".

1. The rule: one correction, one path

2. Who implements what

PieceiPhone (Swift)Windows (C#)
Correction, VocabularyLearning.apply, receipts/undoPull jot-shared 42e2428Port; pass the shared JSON fixtures
EditLearner (edit diff → lessons)PullPort (§4)
VocabularyListWriting adapter (your vocabulary store, by row id)ImplementImplement
Wire every correction surface to applyImplement (keyboard: queue Codable Corrections for the app; it can't write the app's list)Implement
Decoder pairs + weights (DecoderVocabulary.derive)n/a until decode bias (Parakeet)Port if your decoder has bias (§6)
Gate: no learned auto-apply; paused pair blocksPull (fixtures updated)Port; fixtures changed (§7)

3. Correction surfaces (Mac inventory — mirror yours)

SurfaceCall
Edit → DoneEditLearner lessons → .correct (userCasing) / .keepOriginal / .recase
Add to Vocabulary (select text).correct(heard, term, userCasing: true)
Review list: pick term / keep / undo.correct / .keepOriginal / .undo(receipt) — provenance bookkeeping stays per surface; receipt stored per verdict
Popup: confirm / wider-phrase / keep.correct / .correct / .keepOriginal; timeout teaches nothing
Settings: add / remove sounds-like chip.correct(userCasing: true, termID) / .forget (routed by row id)
Settings: delete / rename termplain list write; pairs vanish with the term

Casing: only hand-typed surfaces (userCasing: true) may change the term's spelling. Popup/review proposals can be sentence-start capitalized ("EBay"); they resolve to the list's existing spelling.

Undo: reverses exactly what one correction added — its sounds-like first; the term row only if nothing else is on it and its text is unchanged; flags compare-and-restore.

4. Hand-edit rules (EditLearner.learn)

trim identical start/end; > 2000 changed words → nothing
word-align before vs after (punctuation-insensitive)
per changed hunk:
  pure insert / delete                         → skip
  outside 1–3 → 1–4 words                       → skip
  punctuation- or digit-only                    → skip
  case-only                                     → .recase (not first-letter at sentence start)
  before-side is exactly a vocabulary term      → .keepOriginal (user undid a term)
  before-side has a term among other words      → skip
  both sides everyday AND replacement has no capitalized word → skip  (a→the, your→you're)
  not sound-alike (VocabularyGate.plausible)    → skip  (tomorrow → "on Monday")
  else → .correct(original, term, heardByModel: original ∈ raw, userCasing: true)
one lesson per pair per edit session; languages without an everyday-word list: learn nothing

5. Store (corrections.json, per mapping)

editsToward, editsAway : Int   // up/down history
editHeard              : Bool  // model actually wrote the original
pairPaused             : Bool  // last explicit signal was keep/edit-back
                               // absent key ⇒ editsAway > editsToward
confirmations/reverts/net      // ask-ranking prior ONLY, never an apply
alwaysReplace, editStreak      // REMOVED: still decoded for old files, ignored, dropped on next write

6. Decoder (derived from the list; nothing stored twice)

pairs(term)  = each sounds-like of term that is
               single word, ≥ 3 letters, Latin script,
               SAME FIRST LETTER as the term, not paused
weight(term) = 5.0 if term has an active pair, else 3.5
pair push    = +10 on the term's continuation, −10 on the original's diverging token,
               only where the letters so far are shared; never inside/right after the term
near-completion: a pushed word one trailing letter short of the term (≥ 4 letters),
               not the original itself, is emitted as the term in its own casing
               ("claud" → "Claude")

Measurements (LibriSpeech test-clean, N=100 lists)

SettingResult
One learned term at 5 / 6 / 7 / 8false insertions 0 / 5–8 / 19–56 / 81–251 of 2620 → ceiling 5
Pair push 10 + near-completion, same-first-letter natural pairscorrected-word recall 0.5% → 49.5%; 0/640 word-count changes; U-WER 1.982 → 1.989
Different first letter, everyday original ("chart" → Jot shape)conversion 0.4%; 21/2620 utterances damaged → excluded (stays with the gate)

Windows: your decoder uses start 2.0 / continue 3.0 — keep the ratio and re-measure; do not assume these numbers transfer.

7. Gate + fixture changes (cross-platform contract)

8. Tests to port

9. Status

MacReleased 1.23 (public + Sony). jot-shared 42e2428. FluidAudio fork vineetu/FluidAudio branch jot/learned-pairs @ 0de0032e.

iPhonePull jot-shared 42e2428; adapter + wire surfaces; keyboard queues Corrections.

WindowsPort §1–§7 against the shared fixtures; re-measure decoder numbers.