# Punch-In — origin note

> **Written:** 2026-06-14 · **Owner:** Mohsen Seyedkazemi Ardebili
> **Shipped as:** [`design/specs/punch-in.md`](../../specs/punch-in.md)
> **Tier:** `design/` — public. Historical origin note; the spec above is the current
> source of truth.

## The idea

The pitch borrowed the DAW analogy directly: punch-in recording lets a musician re-perform
just the wrong bar and splice it seamlessly into the take, with no rewind and no cutting
tape. Dictation correction is the same shape of problem — a known-good region, a bad span,
and a re-performance that has to align and splice — except the machine, not an engineer,
has to find the bad span from the re-performance alone. The card was explicit that this is
where the dream meets an empirical ceiling: naive re-dictation of a wrong phrase has a
documented tendency to fail the same way twice, so the design had to build the recognizer's
own failure mode into the correction UX rather than assume repetition alone fixes it.

## What shipped

`src/yazses/postprocess/punch_in.py` locates the spans in the recent dictated buffer
closest to a re-spoken phrase and proposes a replacement, wired to the `punch-in` feature
toggle (**off by default**). It matches the constrained scope the original decision gate
picked: alignment against the recent buffer, not an open-ended edit history, and it shares
its correction-event signal with the encrypted learning corpus (ADR-012) as ground truth,
exactly as flagged in the original card.