Transcript Fixer

Use a two-phase loop:

1. Stage 1 applies deterministic, already-known corrections.
2. Native AI Correction reads the complete transcript, fixes one-off errors, verifies uncertain entities, and compounds reusable fixes.

Native AI Correction is the default. Stage 1 alone is incomplete. Stage 3 API exists only for automation that has no Claude/Codex agent available.

Operating contract

• Finish Stage 1 → Native AI Correction → compound confirmed recurring fixes. Do not report a transcript clean after Stage 1 alone.
• Skip Native AI only when the human explicitly limits this run to the dictionary pass or a dated artifact proves Native AI already ran on this exact transcript.
• In Claude Code or Codex, do not run Stage 3. Use Stage 1 plus the native workflow.
• Never rewrite speech for fluency. A correction must explain a plausible ASR error and preserve who said what.
• A standard term elsewhere or a known participant is a candidate source, not proof of this occurrence's wording. Apply the occurrence-specific contrasts in Native review packets during the first pass and cold review; retain the raw form when the discriminator is missing.
• By default, never infer or reassign speaker identities. Preserve speaker-label lines; human-confirmed labels and user verdicts are authoritative. Only an explicit, task-scoped user grant to infer identities opens the separate derived-reader branch: read scoped speaker inference before acting. That grant is permission to infer, not an identity confirmation or permission for other transcripts.
• Before correcting any person name, directly read both the configured global people roster and the owning project's explicit identity roster or alias ledger. Stage 1 auto-loads only global ASR 变体 entries; it does not load project rosters or expose suppressed, disabled, and unlisted entries. If an expected source is missing or the sources conflict, leave the name unchanged and enqueue or ask once. Never use occurrence frequency as identity evidence. Read references/dictionary_identity_and_context.md before settling the name.
• Resolve doubts from available evidence before escalating. Audio download is one evidence channel, not a prerequisite for Native correction. When it is unavailable, follow evidence selection and escalation; do not require the user to change download permissions or treat every pending row as a question only they can answer.
• Leave genuinely unresolved text unchanged and enqueue it. A visible garble is safer than a fluent wrong guess; a pending row records uncertainty, not an automatic human handoff.
• Treat an unfamiliar token as unknown, not as an error. Exhaust the local evidence ladder first. For a load-bearing token that remains unresolved, use the clip-level cross-recognizer rung only when source audio and a permitted second engine are already available; otherwise continue with the available evidence under the escalation policy above. Agreement from a genuinely different recognizer family strongly corroborates the sound, but never chooses between homophonic spellings or overrides the person-name gate. Read native workflow step 4, rung 7 before using it. A backlog of exhausted pendings is the batch form of this rung: when a native pass leaves a queue of locally-unresolvable rows, do not hand the queue to the user wholesale — check it with verify_queue_audio.py (one transcript, one source audio, one second engine, two clip windows per row). The script can attach acoustic evidence but never records a verdict; identical clips and readings that do not support the disputed word boundary remain pending for adjudication. The operator matrix and timestamp-mapping pitfalls live in advanced_correction_evidence.md § Batch pending adjudication.
• Treat a single-line asr_note value as correction provenance: it intentionally cites old forms and is excluded from matching. Multi-line YAML ledger values are not masked; keywords, titles, other ASR-derived metadata, and body text remain in correction scope.
• Read references/native_ai_full_workflow.md in full before performing a native pass. Contiguous, nonoverlapping reads may cover the full file; if a response is truncated, read the missing range before proceeding. An executed cat does not establish that its full output was received. Read the task-specific references named below before their corresponding action; use bounded, nontruncated reads for those files too.

Run context

Run every entrypoint through uv run; entrypoints that need third-party Python packages declare them with PEP 723, while stdlib/internal-only utilities may omit the metadata block. Execute commands from the skill directory printed when this skill was invoked, or prefix every script path with that directory. Do not rely on $CLAUDE_SKILL_DIR; it is not available in every harness.

If the bundle location is genuinely unknown, use the installation-resolution procedure in references/installation_setup.md. Do not select the first result from a broad find: caches, backups, and old versions can coexist.

Quick start

# Initialize once
uv run scripts/fix_transcription.py --init

# Stage 1 for one project domain. --apply-domain trusts that explicitly
# selected, human-curated project domain at every risk level.
uv run scripts/fix_transcription.py \
  --input meeting.md --stage 1 \
  --domain myproject --apply-domain --json

# Several sibling domains may be loaded as one union.
uv run scripts/fix_transcription.py \
  --input meeting.md --stage 1 \
  --domain myproject,myproject-alt --apply-domain --json

# Preview without writing the Stage 1 output.
uv run scripts/fix_transcription.py \
  --input meeting.md --stage 1 --domain myproject --dry-run

# Scan all documented context traps after the native read-through.
uv run scripts/fix_transcription.py --scan-traps \
  --context-file ~/.transcript-fixer/contexts/myproject.md \
  --input meeting.md

Safe mode is the Stage 1 default: low-risk rules apply; medium/high-risk matches defer to *_needs_review.md and the persistent review queue. Applied: 0 is a valid result, not proof that the transcript is clean.

The Stage 1 JSON contract is:

{
  "applied": 0,
  "deferred": 0,
  "output_path": null,
  "needs_review_path": null,
  "input_unchanged": true,
  "review_enqueued": 0,
  "stage1_only_incomplete": true,
  "stage2_total_chunks": 0,
  "stage2_failed_chunks": 0,
  "stage2_degraded": false,
  "boundary_refused": 0,
  "boundary_check_active": true
}

Read every field in the result. boundary_refused counts dictionary matches the word-boundary check refused this run — neither applied nor deferred, so a caller comparing runs can see why a deferral disappeared; --apply-all switches that check off. stage1_only_incomplete is additive to the original caller contract and must remain true for a Stage 1 script run; only the caller can close it by running Native AI, or by explicitly choosing the agent-less Stage 2/3 route. The stage2_* telemetry fields are always present: Stage 1 reports 0, 0, and false; Stage 2/3 replace them with the actual API outcome. Do not infer no-op or success from whether a sidecar exists.

For a native end-to-end example, read references/example_session_dji_minutes.md.

Choose the route

Route	Use when	Required reading
Pending continuation	Dated Native/review evidence covers this exact file; only uncertain rows remain, or the user supplies a verdict	pending-continuation.md; reuse unchanged completed coverage
Fast native	Short/plain transcript, known speakers, low stakes	This file + native_ai_full_workflow.md
Full native	Domain-heavy, unfamiliar entities, 3+ speakers, long or decision-bearing transcript	native_ai_full_workflow.md, plus queue and evidence references below
Scoped speaker inference	User explicitly authorizes identity inference for this transcript/task	scoped_speaker_inference.md; keep ordinary ASR correction on the native route
Caller integration	Another skill or ingest pipeline invokes Stage 1	Cross-skill caller contract below
Review queue/dashboard	Any item is uncertain or needs audio	review_queue_dashboard.md
Agent-less API	CI/batch automation with no agent available	glm_api_setup.md and workflow_guide.md
Multi-file batch	Several related transcripts; especially 10+ files	advanced_correction_evidence.md

Use vocabulary and stakes as the primary tier signals; use length only as a tiebreaker. A five-minute medical interview can require the full tier, while a long plain two-person memo can use the fast tier.

Native correction checklist

Read the required native sequence in full before correcting. It routes provenance, entity triage, edits, cold-review recovery, queue decisions and finalization to their action-time references.

1. Give the input a final human-readable path; recover/diff raw provenance.
2. Load project context, read the whole transcript, run Stage 1 and inspect its diff.
3. Triage candidates; apply only minimal occurrence-supported corrections.
4. Run the trap scan; complete Full-tier cold review and adjudicate its residuals.
5. Resolve exact-file queue rows; read human state before repeating work.
6. Verify the edited file, require zero pending for final/high-quality claims, close sidecars mechanically, harvest stable patterns and review entity propagation.

Read native action details before the corresponding queue, learning or same-file entity-sweep action. In particular, person-name authority belongs in --authority/--authority-record, not --note; a sentence-local correction is not automatically a reusable rule.

Cross-skill caller contract

A caller pipeline must:

uv run scripts/fix_transcription.py \
  --input "$staged" --stage 1 \
  --domain "$domains" --apply-domain --json