Transcript Fixer

Transcript Fixer

Two-phase correction pipeline: deterministic dictionary rules (instant, free) followed by AI-powered error detection. Corrections accumulate in ~/.transcript-fixer/corrections.db, improving accuracy over time.

What each phase is actually good at (calibration, not a rule): the dictionary shines on recurring errors — product names, common homophones, anything you've corrected before — at zero cost and zero latency. But on a fresh database, on high-quality ASR (e.g. transcripts from a strong engine like Whisper, Otter, or Feishu / Tencent-Meeting), or in specialized domains (finance, medical, legal), the dictionary often matches almost nothing — the errors that remain are proper nouns and domain terms it has never seen. There, the AI pass does essentially all the real work. Treat Stage 1 as a cheap pre-filter for known repeats, not as the primary corrector, and don't be alarmed when it changes only a handful of lines on a clean transcript.

Prerequisites

All scripts use PEP 723 inline metadata — uv run auto-installs dependencies. Requires uv (install guide).

Quick Start

# First time: Initialize database
uv run scripts/fix_transcription.py --init

# Single file — Stage 1 runs in SAFE MODE by default: only low-risk
# (non-word, high-confidence) corrections auto-apply. Medium/high-risk ones
# (common words, "  # From https://open.bigmodel.cn/
uv run scripts/fix_transcript_enhanced.py input.md --output ./corrected

See references/installation_setup.md for the full config-file format and references/glm_api_setup.md for GLM endpoint details.

Core Workflow

Two-phase pipeline with persistent learning:

1. Initialize (once): uv run scripts/fix_transcription.py --init
2. Add domain corrections: --add "错误词" "正确词" --domain
3. Phase 1 — Dictionary: --input file.md --stage 1 (instant, free)
4. Phase 2 — AI Correction: Claude reads output and fixes errors natively, or --stage 3 with the API key configured in ~/.transcript-fixer/config.json for API mode
5. Save stable patterns: --add "错误词" "正确词" after each session
6. Review learned patterns: --review-learned and --approve high-confidence suggestions

Domains: general, embodied_ai, finance, medical, tech, or custom (e.g., legal, gaming) Learning: Patterns appearing ≥3 times at ≥80% confidence auto-promote from AI to dictionary

New safety & review commands

• Safe mode is the Stage 1 default: only low-risk (non-word, high-confidence) corrections auto-apply; medium/high-risk ones (common words, ≤2-char, real-word fragments) are tracked to *_needs_review.md instead of being applied silently. So Applied: 0 on a clean transcript is correct, not a bug — the risky rules are waiting in *_needs_review.md for you or the AI pass to judge. Pass --apply-all to apply every risk level (the old behavior); --review is kept as a deprecated no-op. This reconnects the risk classifier that was being computed and then ignored — but it does NOT eliminate every false positive: rules whose from_text is a 4+ char valid phrase are still graded low and auto-apply (see references/false_positive_guide.md → "The 4+ char real-word blind spot").
• Preview changes before applying: --dry-run writes *_dryrun.md with every planned Stage 1 change and its risk level.
• Always-on changes report: --changes-file writes *_changes.md with before/after/risk for every correction (on by default in safe mode).
• Extract uncertain ASR tokens: --extract-uncertain -i file.md writes *_uncertain.md with likely errors (short all-caps tokens, transliteration fragments, repeated words) without changing the file.
• Load domain presets: --load-presets tech imports a curated set of tech/Claude Code ASR corrections.
• Report false positives: --report-false-positive "错误词" "正确词" -d domain disables a bad dictionary rule and lowers its confidence.
• Audit for risky rules: --audit flags existing rules that look like false-positive sources (common words, ≤2-char, substring collisions, and — with jieba — 4+ char real-word phrases). It is advisory: it surfaces candidates, it does NOT disable anything. Disabling is a human decision — review each hit by hand and back up the DB first, because the audit cannot know your context and mislabels a large fraction of good rules (e.g. GDP 5.5→GPT 5.5 looks wrong generically but is a correct fix for an AI-heavy user). See references/false_positive_guide.md.

After fixing, always save reusable corrections to dictionary. This is the skill's core value — see references/iteration_workflow.md for the complete checklist.

Dictionary Addition After Fixing

After native AI correction, review all applied fixes and decide which to save. Use this decision matrix:

| Pattern type | Example | Action | |-------------|---------|--------| | Non-word → correct term | 克劳锐→Claude, cloucode→Claude Code | ✅ Add (zero false positive risk) | | Rare word → correct term | 拉行链→LangChain, 哈金费斯→Hugging Face | ✅ Add (verify it's not a real word first) | | Person/company name ASR error | 卡帕西→Karpathy, Anthropics→Anthropic | ✅ Add (stable, unique) | | Common word → context word | 争→蒸, affect→effect | ❌ Skip (high false positive risk) | | Real brand → different brand | Xcode→Claude Code, Clover→Claude | ❌ Skip (real words in other contexts) |

Batch add multiple corrections in one session:

uv run scripts/fix_transcription.py --add "错误1" "正确1" --domain tech
uv run scripts/fix_transcription.py --add "错误2" "正确2" --domain business
# Chain with && for efficiency

False Positive Prevention

Adding wrong dictionary rules silently corrupts future transcripts. Read references/false_positive_guide.md before adding any correction rule, especially for short words (≤2 chars) or common Chinese words that appear correctly in normal text.

Project-Specific & Person-Name Corrections (--domain isolation)

The most important pattern for recurring, project-specific errors — person names, project jargon, product codenames — is the --domain flag. It is also the answer to the false-positive worry above: a person-name fix that's right in your project (a teammate's name the ASR keeps garbling) might collide with a real, differently-spelled person in someone else's transcript — so it must NOT go into the global (general) dictionary.

--domain makes such rules safe by isolating them:

# Add the rule under an isolated, project-named domain (not 'general')
uv run scripts/fix_transcription.py --add "" "" --domain 
# Apply ONLY that domain's rules to this project's transcripts
uv run scripts/fix_transcription.py --input meeting.md --stage 1 --domain 

A rule added under --domain only fires when you pass --domain at correction time. Other projects (their own domain, or default all) are unaffected — so even a risky short-word / common-word person-name rule is safe, because it only fires inside the project where it's correct.

Why this beats a one-off script (the core value, do not skip)

Facing a transcript — or a whole batch — full of the same ASR-garbled names, the tempting move is a quick sed / python find-and-replace. Don't. That is the single biggest anti-pattern with this skill:

• A throwaway script fixes this batch and the knowledge then evaporates: next batch, next week, next project, you rewrite it from scratch. It does not compound.
• The dictionary compounds: --add once, and every future transcript auto-corrects via --stage 1 --domain . Wire that one command into the project's ingest step and the names are fixed forever, for free.
• The dictionary has false-positive protection (short-word warnings, the audit command, --report-false-positive); a raw sed has none and will silently corrupt look-alike words.

Rule of thumb: recurring or project-specific error → --add ... --domain (it compounds). Never a throwaway sed/python replace. A one-off script is acceptable only for a genuinely one-time, never-recurring fix — and even then the dictionary is usually less effort.

ASR is especially unstable on Chinese names: one person can shatter into a dozen homophone variants (in one real project a single surname+given-name was seen as 13+ [姓变体]×[名变体] combinations). Capture every confirmed variant with --add --domain so they all collapse to the canonical name on every future run.

Native AI Correction (Default Mode)

When running inside Claude Code, use Claude's own language understanding for Phase 2 — on high-quality ASR this is where almost all the real correction happens. Scale the effort to the transcript. A short, clean recording with no proper nouns (a quick voice memo) just needs steps 1-3 plus one obvious-fix pass; skip the verification / second-pass / subagent / needs-checking machinery below, which earns its keep on long, multi-speaker, domain-heavy, or high-stakes transcripts. Don't turn a 10-second memo into a research project.

1. Run Stage 1 (dictionary) on all files (parallel if multiple)
2. Verify Stage 1 — diff against the original. If the dictionary introduced false positives, work from the original file instead and apply your edits there
3. Read the entire transcript before proposing corrections — later context disambiguates earlier errors (a name garbled near the start often becomes obvious later). For large files, read in chunks but finish the whole thing before deciding anything
4. Triage each candidate error into one of three buckets — this triage is the part that takes judgment:

• Confident fix — non-words, obvious garbling, product-name variants you already recognize, or a homophone that's unambiguous in context (their→there where context forces it; 彭波→彭博 when every other mention already reads 彭博). Apply directly (step 5).
• Needs verification — a proper noun you can't confirm from context: a person / company / ticker / product / place name (a misheard drug name in a medical interview, a researcher's surname in a podcast, a ticker on an earnings call), or any term you can't point to a specific source for — even one you think you recognize ("I'm pretty sure" is exactly how wrong names slip in). Search it, don't guess — WebSearch, or a local grep if it's a project / personal entity. A confirmed result becomes a Confident fix; if the search can't confirm it, it drops to Uncertain. Batch these: collect the unique unknowns and look them up together, not one-by-one.
• Uncertain — you suspect an error but can't confirm it even after searching (a syllable that maps to several real entities; a structurally broken sentence). Leave the original text exactly as-is and record it in the needs-checking list (step 7). A fluent-but-wrong "fix" is harder to catch downstream than an obvious garble — silence beats a confident guess.

1. Apply the confident fixes efficiently:

• Global replacements (unique non-words like "克劳锐"→"Claude"): if it recurs across transcripts — most product/name garbles do — --add it to a --domain so it compounds to every future run; for a genuinely one-off term, one sed -i '' with multiple -e flags
• Context-dependent (a word that's only wrong in one context, like "争"→"蒸" in a distillation discussion): sed with a longer surrounding phrase for uniqueness, or the Edit tool
• Re-grep each changed term afterward to confirm it landed and didn't hit look-alikes you meant to keep

1. Second pass — catch what one read missed. A single linear read reliably leaves residue: an idiom degraded into a near-homophone, a term wrong in just one spot among many correct ones, an acronym misheard as another. Always re-scan once for leftovers. For a long or high-stakes transcript, also spawn an independent subagent (Task) to re-read the corrected file cold — fresh eyes with no memory of your first pass catch what you've read past. Have it report suspected residuals with line numbers, then run each back through step-4 triage (fix / search / log). Task works when you're in the main context; if it isn't available — e.g. these instructions are themselves running inside a subagent, which can't spawn another — just do one more thorough independent re-read yourself. Never skip the second pass over a missing tool.
2. Emit a needs-checking list — in your chat summary to the human, not baked into the file — for everything still Uncertain: line number, the original text you left in place, what you suspect, and why you couldn't confirm it. This surfaces the few items that need a recording or source to resolve, instead of burying them or papering over them with guesses. If nothing is uncertain, say so.
3. Verify with diff against the file you actually edited (diff ) — every change should trace back to a triage decision
4. Finalize: rename *_stage1.md → *.md, delete the original .txt. Use /bin/mv -f, not a bare mv — on macOS mv is commonly aliased to mv -i, which prompts before overwriting an existing target and, with no interactive answer, defaults to "no" and skips the move while still exiting 0. A bare mv … && echo done then reports success while the un-corrected file silently survives as the final output. After renaming, re-grep the final file for a correction you know you applied (e.g. a fixed name) to confirm the corrected version is what landed.
5. Save stable patterns to the dictionary (see "Dictionary Addition" below)
6. If you worked from corrected_stage1.md, strip any remaining Stage 1 false positives before finalizing

Common ASR Error Patterns

AI product names are frequently garbled. These patterns recur across transcripts:

| Correct term | Common ASR variants | |-------------|-------------------| | Claude | cloud, Clou, calloc, 克劳锐, Clover, color | | Claude Code | cloud code, Xcode, call code, cloucode, cloudcode, color code | | Claude Agent SDK | cloud agent SDK | | Opus | Opaas | | Vibe Coding | web coding, Web coding | | GitHub | get Hub, Git Hub | | prototype | Pre top |

Person names and company names also produce consistent ASR errors across sessions — always add confirmed name corrections to the dictionary, and for project-specific names use --domain to keep them isolated (see "Project-Specific & Person-Name Corrections").

Efficient Batch Fix Strategy

When fixing multiple files (e.g., 5 transcripts from one day):

1. Stage 1 in parallel: run all files through dictionary at once
2. Read all files first: build a mental model of speakers, topics, and recurring terms before fixing anything
3. Compile a global correction list: many errors repeat across files from the same session (same speakers, same topics). If an error recurs — especially a person name or project term — --add it to a project --domain (see "Project-Specific & Person-Name Corrections" above) instead of replacing it inline; it then auto-fixes every future file, not just this batch.
4. Apply the remaining one-off corrections (sed with multiple -e flags, for genuinely non-recurring fixes only), then per-file context-dependent fixes
5. Verify all diffs, finalize all files, then do one dictionary addition pass

Parallel via Dynamic Workflow (large batches)

For a large batch (10+ files), a Dynamic Workflow — one subagent per file, running in parallel — is faster than a shell loop and gives each file full AI attention. Four rules earned the hard way; skipping any of them has caused real damage:

1. Hardcode the file list into the script — don't pass it through args. A Workflow args array of strings containing non-ASCII characters, brackets, or path separators can silently arrive empty: the script sees zero files, no agents spawn, and it exits instantly with something like "no files". Plain alphanumeric tokens pass fine, but file pat

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: daymade
• Source: daymade/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.