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

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:

1. Run Stage 1 with the explicitly configured project domain(s), --apply-domain, and --json. If deferred > review_enqueued, persist the review sidecar outside any temporary directory or surface the gap as failure.
2. Run Native AI with this skill loaded, or report Stage 1 only — incomplete. Agent-less automation may use Stage 3 instead.
3. Select the report location from the destination's storage contract. Use --sidecar-dir DIR for review reports while keeping run outputs under the existing --output contract. Omission preserves adjacent/default output behaviour; retain pending reports until --close-sidecars decides closure. Closure discovers registered custom report directories, or accepts --sidecar-dir explicitly for recovery. Never force every project to move reports into one fixed subdirectory.

Canonical call:

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

A caller that wires only the script path never loads this contract. Script-path integration alone is therefore a Stage 1 prefilter, not transcript correction.

Keep project domains warm: every confirmed recurring correction from the native pass must be added back to the correct project domain, roster, or context file.

Conditional actions

Read the matching section before acting; these are existing supported jobs:

Detection and enqueueing are not correction. A final/high-quality claim requires exact-file stats.pending_total == 0; zero pending rows is required after the file edits are read back. An unresolved file stays draft / unresolved — incomplete. A sampled clip settles only that anchored item. For high-stakes multi-recording requests for a complete/better transcript with baseline audio available, load /daymade-audio:asr-transcribe-to-text and cover the complete clearest recording; the same recognizer proves complete-source coverage, not independent corroboration. User verdicts settle occurrences, but they do not make a replacement reusable: a rare sentence-local mishearing stays file-only.

Reference map

All references are one level from this file.

Bundled scripts are executed, not loaded into context. The primary entry points are fix_transcription.py, scan_numeric_consistency.py, fetch_minute_audio.py, review-dashboard/server.py, and the diff/timestamp/splitting utilities listed above.

Handoff

After correction, hand off to /daymade-audio:meeting-minutes-taker only when the user wants a structured summary. Do not create meeting minutes automatically: transcript correction and summarization are separate scopes.