Listen

Voice input reaches the agent as text that already passed through a speech-to-text engine. Good engines hold 5-10% word error rate on clean conversational English, but the errors concentrate exactly where meaning lives: proper nouns, domain jargon, and numbers. This skill is the repair layer between the raw transcript and your response. Learned corrections and preferences persist in ~/Clawic/data/listen/ (see setup.md on first use, lexicon.md for the file formats). If you have data at an old location (~/listen/ or ~/clawic/listen/), move it to ~/Clawic/data/listen/.

When To Use

• A message arrived via voice and one token breaks the sentence ("deploy the communities cluster")
• The user repeats, rephrases, or says "no, I said X" after your response or action
• The same name, product, or term gets mangled across sessions and needs a persistent fix
• The user dictates an artifact by voice — an email, message, document, or note
• A voice command feeds an action with side effects (send, delete, book, pay) and a token looks off — repairs that change the target of such an action are always confirmed with the user before anything runs (Rule 1)
• A transcript arrives noisy, truncated, mixed-language, or padded with hallucinated sentences
• An STT engine needs vocabulary tuning for a user's recurring domain terms
• Not for transcribing audio files (that is batch transcription work) and not for typed-text typos: keyboard errors are adjacency-based, so phonetic repair misfires on them

Quick Reference

Depth on demand: repair.md candidate generation and phonetic matching · numbers.md digits, times, money, spoken addresses · names.md proper nouns, casing, code identifiers · dictation.md producing dictated artifacts · actions.md side-effect confirmation ladder · degraded.md noise, hallucinations, truncation · multilingual.md code-switching and accents · tuning.md upstream engine fixes · lexicon.md correction persistence · setup.md first-use preferences.

Core Rules

1. Repair without confirmation when only understanding changes; confirm when the repair changes an action target. Check: would acting on raw vs repaired text produce different side effects (recipient, amount, file path, send/delete)? Different side effects = confirm first. Same outcome = fix without asking and move on. Full ladder in actions.md.
2. Confirm with a candidate, never an open question. "Did you mean Kubernetes?" costs the user one word; "What did you say?" forces full re-dictation. Offer 1 candidate; 2 only when both fit equally; never 3.
3. Two-strike promotion. First observed fix = candidate: apply it but surface it ("...on Kubernetes, got it"). Same fix observed a second time = confirmed: apply from then on without surfacing it. One user rejection at any stage = move the pair to the Never list.
4. Repair needs two independent signals: phonetic closeness AND context fit. Phonetic test: fold confusable consonants (B/P, D/T, C/K/Q — full class table in repair.md), strip vowels, collapse doubles, then compare skeletons. "web look" → WPLK vs "webhook" → WPHK is skeleton edit distance 1 (one substitution, L/H); distance ≤2 = neighbor. Context test: the candidate must be a term already in this user's domain (lexicon, recent files, session topic). Either signal alone is a guess, not a repair.
5. Correction direction is common-word → proper-noun, almost never the reverse. STT engines are biased toward frequent vocabulary, so a rare word that survived transcription was almost certainly spoken. Never "fix" an odd-looking codename into a dictionary word.
6. Echo digits for any number that gates an action. "Booked for 15 (one five) at 8pm." The seven -teen/-ty pairs are the highest-frequency STT number confusion (numbers.md), and a wrong booking count costs more than three extra characters in every reply.
7. A fluent sentence that ignores the conversation is the engine, not the user. Whisper-family models emit caption boilerplate ("Thank you.", "Thanks for watching!") on silence or noise-only audio. Drop it; interpreting it as user intent invents a request nobody made. Signatures in degraded.md.
8. 3+ suspect tokens = stop repairing tokens. Piecewise repair of a noise-storm transcript compounds guesses into a sentence the user never said. Quote your full best-effort reading back for a single yes/no instead.

Repair Procedure

1. Flag the suspect token: it breaks domain, register, or grammar of the surrounding sentence.
2. Generate candidates in priority order: (a) lexicon entries whose wrong-side matches, (b) phonetic neighbors (Rule 4 skeleton test) drawn from session vocabulary, open files, and recent topics, (c) re-segmentation splits/joins.
3. Score by context fit; discard any candidate failing the two-signal test of Rule 4.
4. Route by Rule 1: side effects → confirm with the top candidate; understanding only → substitute without confirmation.
5. After user confirmation or correction, append the pair to the lexicon (lexicon.md).

Worked candidate generation, sound-class folding, segmentation repair, and the homophone catalog: repair.md.

Correction Lexicon

One line per pair in ~/Clawic/data/listen/lexicon.md:

wrong → right | status: candidate|confirmed|never | last seen: YYYY-MM-DD
web look → webhook | confirmed | 2026-07-23

• Load the lexicon before interpreting any voice message; apply confirmed entries pre-emptively.
• never entries are false positives (slang, codenames the user actually says); check them before flagging any token.
• Lifecycle, pruning thresholds, and the config file format: lexicon.md.

Output Gates

Before replying to any voice-sourced message, check:

• Did any repaired token feed an action with side effects? If yes, was it confirmed or lexicon-confirmed?
• Is every action-gating number echoed as digits somewhere in my reply?
• Am I mentioning transcription or mishearing anywhere except inside a confirmation question?
• Did this exchange produce a new wrong → right pair, and is it written to the lexicon?
• If I produced a dictated artifact: are self-corrections applied, filler handled per dictation_mode, and uncertain tokens marked?
• Did I drop (not interpret) any hallucinated or looped text?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/listen/config.yaml.

Preference areas to record as the user reveals them:

• vocabulary domain — the user's field (dev, medical, legal, finance); seeds candidate scoring in repair.md and biasing terms in tuning.md
• artifact formatting — punctuation habits, paragraphing, sign-offs for dictated emails and documents; affects dictation.md output
• engine and tooling — which STT engine, model, and capture setup the user runs; targets the advice in tuning.md
• channel mix — voice-only vs mixed typing-and-voice sessions; affects which messages get repair at all (typed input is never phonetically repaired)
• spelling conventions — NATO vs plain letters when confirming spellings, diacritics handling for names; affects names.md confirmations

Traps

Where Experts Disagree

• Silent vs surfaced repair. Transparency school surfaces every fix; fluency school hides all of them. The working boundary: surface while a pair is candidate, go silent once confirmed, and always confirm when side effects ride on the repair (Rules 1 and 3). Full transparency is available on request — the lexicon is a readable file.
• Cleaned vs verbatim dictation. Smart-dictation products clean filler and apply self-corrections; court-reporter style keeps every word. Default cleaned; verbatim when the user asks for exact words or the artifact is quoted testimony. dictation_mode records the user's side.
• Fix upstream vs repair downstream. Engine vocabulary biasing kills recurring errors at the source but over-biasing makes the engine hallucinate the boosted terms into unrelated audio. Boundary: 5+ recurring terms justify upstream tuning (tuning.md); one-off errors stay downstream in the repair layer.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/listen (install if the user confirms):

• speech-to-text-transcription — batch transcription of audio and video files with timestamps and speakers
• voice-notes — organizing accumulated voice transcripts into a searchable knowledge base
• talk — setting up the real-time voice conversation channel this skill repairs
• audio — cleaning noisy recordings before they ever reach the STT engine

Feedback

• If useful, star it: https://clawic.com/skills/listen
• Latest version: https://clawic.com/skills/listen

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/listen.