transcript-fixer

Transcript Fixer

默认模式：Claude 内置 AI（Native AI Correction）——无需任何外部 API key。 Stage 1 字典纠错（免费、即时）→ Claude 自己读原文做智能纠错 → compound 进字典。 Stage 3 API 仅用于无 Claude Code 的自动化批处理场景（备选）。

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).

The commands below use relative script paths (scripts/<name>.py), so they only work from the skill's own directory — and in agent harnesses the shell's working directory resets between calls, which surfaces as Failed to spawn: scripts/fix_transcription.py on the very first command. Take the skill directory from the "Base directory for this skill" line printed when this skill was invoked, and either cd there in the same command or prefix every script path with it. Do not rely on $CLAUDE_SKILL_DIR — it is unset in at least some harnesses (verified 2026-08), so a command built on it fails with the same error it was meant to prevent. If you no longer have the invocation line, find -L ~/.claude ~/.codex -name SKILL.md -path '*transcript-fixer*' locates the bundle — but it returns dozens of hits — every installed version, plus backups, staging copies and pre-edit snapshots — and the first is not the newest. Skip any path containing skill-before, -workspace, source-sync-backups, .tmp or .staging. Among what remains, prefer the highest version directory; some installs (a marketplace checkout, another agent's skills dir) carry no version at all, so if you end up choosing between those, take the one with the newest mtime and sanity-check it against this file's content before trusting it.

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, <=2-char, real-word fragments) are written to
# *_needs_review.md for you / the AI pass to judge, not applied silently.
uv run scripts/fix_transcription.py --input meeting.md --stage 1

# Trust ONE project domain's rules (recommended for batches): rules of the
# domain you explicitly pass via --domain apply at every risk level — they were
# hand-confirmed for this project's vocabulary, so domain match = trust. The
# roster and everything else keep safe-mode deferral. One pass instead of three
# (safe run -> review sidecar -> --apply-all rerun).
uv run scripts/fix_transcription.py --input meeting.md --stage 1 --domain myproject --apply-domain

# Sibling domains load together (comma-separated) — one project's vocabulary
# often lives in several domains that grew at different times (myproject,
# myproject-alt, ...), and a transcript that straddles them should be fixed in
# ONE pass, not one rerun each. --apply-domain trusts the whole union.
uv run scripts/fix_transcription.py --input meeting.md --stage 1 --domain myproject,myproject-alt --apply-domain

# Which domains does this project even have? A 0-correction run prints the
# hint listing every OTHER domain with its rule count — read it, then rerun
# with the siblings added. (Write commands like --add stay single-domain.)

# Apply EVERY risk level regardless of origin (the pre-safe-mode behavior).
# Higher false-positive risk — only when you've reviewed ALL loaded rules.
uv run scripts/fix_transcription.py --input meeting.md --stage 1 --apply-all

# Dry run: preview all Stage 1 changes (with risk levels) without writing *_stage1.md
uv run scripts/fix_transcription.py --input meeting.md --stage 1 --dry-run

# Extract likely ASR errors without applying any corrections
uv run scripts/fix_transcription.py --extract-uncertain -i meeting.md -o ./review

# Batch: multiple files in parallel (use shell loop)
for f in /path/to/*.txt; do
  uv run scripts/fix_transcription.py --input "$f" --stage 1
done

# ⚠️ STOP — Stage 1 alone is NOT the job. It is the pre-filter, not the
# corrector: on clean ASR (Feishu / Tencent / Whisper) the dictionary often
# matches almost nothing, and the Native AI pass below does essentially all
# the real work. Reporting "transcript clean" after Stage 1 alone is the
# recurring failure this skill exists to prevent (real case, 2026-08: an
# ingest pipeline ran Stage 1 on a 73-min transcript, got 0 hits, declared
# it clean — 54 errors were later found by the native pass it skipped).
# "The dictionary applied N fixes" does not change this either.
# "Done" = Stage 1 → Native AI Correction → --add the confirmed fixes.

After Stage 1, Claude reads the output and fixes remaining ASR errors natively (no API key needed) — this is the primary path, and skipping it is not a valid shortcut, even for a quick transcript (a "quick, clean" transcript is exactly where the dictionary is weakest and the native read matters most). The full method — triage by confidence, verify-don't-guess, second pass, needs-checking list — is in Native AI Correction below; read that section as the source of truth. For a quick, clean transcript it collapses to: read the domain's context file if one exists (~/.transcript-fixer/contexts/<domain>.md) → read the whole thing → fix the obvious one-off errors inline → --add any recurring or project-specific ones (especially names) to a --domain dictionary so they auto-fix next time (see "Project-Specific & Person-Name Corrections"). If you are finishing after Stage 1, name explicitly why the native pass does not apply — "the pipeline ran the script" is not a reason. The only valid exemptions: the human user explicitly scoped this one run to the dictionary pass (a caller pipeline's standing "run Stage 1" wiring is NOT this exemption — see "When called by another skill" below), or you have evidence the native pass already ran on this transcript (a dated note in the file or the ingest log). "The transcript looked short/clean", "the dictionary already applied N fixes", and "I'm in a hurry" are not exemptions — they are the failure.

See references/example_session.md for a concrete input/output walkthrough.

⚠️ Stage 3 API — 备选方案（仅限无 Claude Code 的自动化批处理）

如果你正在 Claude Code 里运行此 skill，跳过本节——直接用上面的 Stage 1 + Native AI Correction，不要跑 --stage 3。 Stage 3 是给 CI/脚本/无 Claude 环境的批量自动化用的，需要额外配置 GLM API key。

# 备选: 仅限无 Claude Code 的批处理
export GLM_API_KEY="<api-key>"  # 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 <domain>
3. Phase 1 — Dictionary: --input file.md --stage 1 (instant, free)
4. Phase 2 — AI Correction（默认: Claude 内置 AI）: Claude reads the Stage 1 output and fixes remaining errors natively — this is the primary path, no API key needed. The full method is under Native AI Correction below. 备选: --stage 3 API 模式仅限无 Claude Code 的自动化批处理(需额外配置 GLM API key——见上方 §⚠️ Stage 3 API)。在 Claude Code 内不要跑 --stage 3。
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: Repeated AI corrections are written to SQLite history; --review-learned turns high-confidence repeated patterns into pending suggestions, and --approve FROM TO promotes the exact suggestion into the 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).
• Machine-readable status for callers (--json): prints ONE line of {applied, deferred, output_path, needs_review_path, input_unchanged, review_enqueued} on st

Content truncated.