audit-transcription

What this skill does

# Audit transcription

## Posture

Auto-transcribed text is noisy in domain-specific ways. The user almost always knows what they actually said; you don't. **Your job is to flag, not to correct.** Every interpretation is a hypothesis until the user confirms it.

You will be wrong about some flags even when you're well-grounded in context. That's fine — it's expected. What's not fine is silently applying corrections the user hasn't seen.

## Workflow

### 1. Read the whole transcript before flagging anything

You can't tell what's mangled until you know the topic and shape. Skim end-to-end first.

### 2. Pull in domain context the user has documented

Before guessing at vocabulary, check what's actually in the user's world:

- Project notes, AGENTS.md / CLAUDE.md, glossaries
- Related notes the transcript references
- Recent commits, working logs, specs

If a transcribed proper noun doesn't match anything in their documented vocabulary, **don't substitute a similar-sounding name from your own knowledge** — flag it and ask.

### 3. Triage into three confidence tiers

| Tier | Example | What to do |
|------|---------|------------|
| **High — recurring vocabulary** | A phonetic mishearing of a domain term that appears throughout the transcript (e.g. a tool, product, or library name consistently rendered as a similar-sounding non-word) | Propose find/replace |
| **Medium — sentence-level gist** | A garbled clause whose meaning is recoverable from context | Propose your interpretation **as a question**: "I think you were saying X here — does that match?" |
| **Low — unrecoverable** | A sentence where multiple consecutive words are nonsense and the surrounding context doesn't pin down what was being said | Flag as garbled. Do not reconstruct. |

### 4. Surface flags as a list, not as edits

Show the user the triage grouped by tier. Wait for their pass:
- They will confirm some, correct others, and reject a few entirely.
- Treat each correction as a context update — apply it across the rest of the transcript before continuing.
- Don't argue. If the user says "that's not a word we use" about one of your guesses, drop it and don't relitigate.

### 5. Apply edits in-place only after confirmation

For high-confidence vocabulary: inline find/replace.

For medium/low-confidence stretches: wrap with a callout that preserves the original beneath the gist.

```markdown
> [!warning] Transcription note (Garbled)  
> gist: <one-paragraph reconstruction of what was being discussed>

<original garbled text left intact>
```

Never strip the raw transcript. The audit makes a noisy record readable; it doesn't replace it.

### 6. Annotate the file at the top

After edits, add a `## Transcription notes` section above the transcript with:

- A note that the transcript is auto-generated
- The recurring-vocab glossary (so future readers and agents don't re-derive it)
- Single-occurrence corrections that surprised you or that the user explicitly confirmed
- A pointer to the callout format used for unrecoverable passages

Update the frontmatter `description` to mention auto-transcription and the notes section.

## Anti-patterns

- **Don't guess at proper nouns from your own knowledge.** A name that sounds plausible to you may be invented. Flag, ask.
- **Don't rewrite garbled sentences with confident prose.** Even when you think you know what was said, write the gist as a hypothesis in a callout, not as edited dialogue.
- **Don't batch corrections without showing the user first.** Auto-mode does not override "wait for user confirmation on interpretive judgments."
- **Don't keep pushing a guess after the user corrects you.** The correction itself is information about how they think — incorporate it into how you flag the rest.
- **Don't claim you've recovered something you haven't.** If a clause is gone, mark it `[transcription unintelligible]` rather than fabricating.

## When the user is the only source of truth

If you can't ground a flag in any documented context — no glossary, no project notes, nothing in the codebase — say so explicitly when surfacing the flag. Frame it as "no idea what this is, and nothing in your notes resolves it" rather than producing a confident-sounding guess. The user will tell you, and that's the right division of labor.