Edmund debugging playbook

Date-stamped 2026-07-05. Runbook for triaging any Edmund bug. Start at the triage table, run the discriminating first check before forming a theory, and check the open-bug inventory before declaring a discovery.

When NOT to use

• Making a change, not chasing a bug → edmund-change-control.
• You already know the bug is live-only and need to build a deterministic repro → edmund-live-repro-and-diagnostics (full ladder detail; summary in §5 here).
• Caret-drift class specifically, with its six-round history → edmund-caret-integrity-campaign.
• Build/toolchain/stale-binary mechanics beyond the quick checks here → edmund-build-and-env.
• Release, signing, appcast, Sparkle pipeline → edmund-release-and-operate.
• TextKit 2 / AppKit API semantics reference → textkit2-appkit-reference.
• Launch flags and settings keys reference → edmund-config-and-flags.
• How past investigations were run and why → edmund-failure-archaeology, edmund-research-methodology.
• Pre-merge verification of a fix → edmund-validation-and-qa.

1. First 15 minutes — any new bug

Run this checklist before hypothesizing. Every step is cheap; skipping them is how rounds 1–5 of delete-drift shipped fixes that came back.

1. Check the open-bug inventory (§6). If the symptom matches a known open bug, you are done triaging — link the backlog entry and its repro asset.
2. Get the logs. ls -t ~/.edmund/logs/ and read the day's file (edmund-YYYY-MM-DD.log). Grep for the three permanent breadcrumbs:

   grep -n "healing storage edit that bypassed didChangeText\|repairing content above origin\|recovered stranded desync on focus regain" ~/.edmund/logs/edmund-*.log
   

   Also grep for invariant: (the always-on storage==rawSource tripwire) and ⚠︎LEN-MISMATCH.
3. Find the first bad line and walk BACKWARDS. The user-visible symptom is often the second half of a two-part mechanism — the round-6 caret drift was armed by a silent bypass 80 seconds and dozens of healthy edits before the leap. Never start reading at the symptom timestamp.
4. Rule out a stale build if this follows a rebuild: grep strings .build/arm64-apple-macosx/debug/edmd for a long string literal unique to the new code (≤15-byte literals are inlined on arm64 and never appear); shasum the binary. See §3c.
5. Check git history for prior art. git log --oneline -- <suspect file> plus the investigation docs in docs/. The viewport-glitch investigation found four earlier fixes all working around the same unnamed root cause.
6. Reconstruct the document. Get the user's file or rebuild it from the trace's block counts/lengths. Wrapped-paragraph geometry and block kinds matter; do not repro against "hello world".
7. Before touching any running app: pgrep -lx edmd then ps -o lstart=,command= -p <pid>. The user's daily-driver app shares the binary name. Never blanket pkill -x edmd — kill only the PID you launched.
8. Row found in §2 → run its discriminating check. No row → escalate per §5, and add the new row here when it's understood.

2. The triage table

3. The traps that cost real time

Each of these burned hours to days. Read before shipping any fix.

(a) Shipping caret fixes on reasoning alone. Delete-drift rounds 1–5 each shipped a plausible, well-argued fix — and each came back. Only round 6, the first with a frozen deterministic live repro (bypassdelete script), named the actual mechanism (_fixSelectionAfterChangeInCharacterRange queued by a bypassed edit, firing at the next endEditing) — and its first fix attempt failed in the repro within a minute, which reasoning would never have caught. Lesson: time spent making the failure cheap to observe beats time spent reasoning about the fix. Freeze the repro before writing the fix.

(b) Undo/redo viewport drift. Two defects hid behind one symptom: restoreSnapshot ran a full recompose (discarding all TK2 layout, so the follow-up scroll measured freshly manufactured estimates) and performUndo recorded the redo snapshot with the caret at undo-invocation time, not at the edit. Lesson: a wrong-scroll symptom can be a geometry bug and a plain stale-state bug stacked; fix and verify them separately. The contract since 5bb2b40: diff the snapshot, apply via recomposeReplacing, select the changed text, let the changed range drive the viewport.

(c) Stale binaries produce false conclusions. In round 6, swift build twice printed Build complete! while linking a stale edmd — the compile ran, the relink silently didn't — and two "failed" fix iterations were phantoms. Detect: grep strings on the binary for a long literal unique to the new code. Cure: swift package clean (or rm -rf .build for release weirdness). Never hand-delete .build/…/edmd.build/ — that corrupts the output-file-map and wedges the target until a full clean.

(d) Headless-green ≠ fixed for input-layer bugs. The round-6 unit test reconstructs the exact document and gesture and passes with and without the fix: the test harness runs AppKit's deferred selection fixup synchronously, so the broken state never forms. A green test proves nothing about the live NSTextView / TextKit 2 / input-context class. The scripted live repro is the regression harness; the unit test is only a contract spec.

(e) open -a runs stale cached copies. LaunchServices can foreground an already-running instance instead of relaunching, and can execute a stale cached/translocated copy of the bundle — you debug last hour's code. Always launch by direct exec: build/Edmund.app/Contents/MacOS/edmd file.md & (after the §1 step-7 pgrep check).

(f) Trusting off-screen fragment y-coordinates. A TK2 fragment's frame is real only once laid out; everything off-screen, plus total document height, is an estimate. Any code that measures before ensuring layout of the viewport↔target span lands wrong (this is Bug 1a, the typewriter-scroll gotcha, and most historical viewport glitches). Ensure layout for the target range first, then align to real geometry — and never verify a visual fix from headless layout: measure from screencapture pixels.

4. Discriminating experiments — cheap checks that split hypothesis spaces

Verbose diagnostics launch (defaults keys are namespaced; the file must be argv[1]):

build/Edmund.app/Contents/MacOS/edmd FILE.md \
  -settings.general.diagnosticLogging YES \
  -settings.advanced.verboseEditorDiagnostics YES

Or toggle in Settings ▸ Advanced ("Save diagnostic logs" + "Verbose editor tracing"). Logs land in ~/.edmund/logs/edmund-YYYY-MM-DD.log.

Trace field vocabulary (source of truth: Sources/EdmundCore/TextView/EditorTextView+Diagnostics.swift, diagnosticState). Every trace line ends with:

Healthy vs suspect edit orderings:

• Healthy: shouldChangeText → selectionDidChange (up=N) → synced. A transient ⚠︎LEN-MISMATCH between those lines is normal (storage moves before rawSource syncs).
• Suspect: a selectionDidChange with up=Y at a surprising position; a persisting LEN-MISMATCH; a shouldChangeText with no synced/SKIPPED/DEFERRED line after it (bypassed didChangeText); the healing storage edit that bypassed didChangeText breadcrumb.

traceSelectionOrigin: under verbose tracing, any selection change arriving mid-recompose (up=Y) or with an unconsumed pendingEdit logs a condensed call stack naming the AppKit path that moved the caret. This is what named _fixSelectionAfterChangeInCharacterRange in round 6. If your bug moves the caret and you don't know who moved it, this answers it in one run.

Walk backwards from the first bad line, not forwards from the symptom. The round-6 drift was armed 80 seconds before the visible leap. Find the first line whose state is wrong, then read earlier.

verifyEditorInvariants (same file): the O(1) length check (storage.length != rawSource.length) logs an error whenever logging is on — no verbose toggle needed — so a hard-invariant break always leaves an invariant: line. The full structural checks (string equality, blocks reconstruct rawSource, block ranges in bounds) run under verbose tracing and assert in DEBUG. An invariant: error in a user's log is a model desync, full stop; triage as the delete-drift class.

If the existing logging didn't capture the deciding fact, add the log line first and reproduce again — one breadcrumb beats ten speculative fixes. Keep good ones behind Log.shouldTrace and ship them.

5. The escalation ladder (summary)

Full detail, ReproScript command reference, CGEvent driver, and soak-script method: edmund-live-repro-and-diagnostics and docs/dev-guides/live-repro-guide.md. Work down; stop at the first level that reproduces.

1. Plain unit test (makeEditor()) — model/parsing/styling logic.
2. Windowed unit test (NSWindow + NSScrollView, real deleteBackward) — adds layout, viewport, first-responder. Failure to repro here is evidence, not defeat: it points at deferred/queued AppKit state and at levels 3–4.
3. In-process ReproScript — DEBUG builds accept -debug.reproScript <path> (Sources/edmd/App/ReproScript.swift); replays a keystroke script through the real window.sendEvent path. No Accessibility/TCC needed, works with the window on an invisible Space. Commands: sleep, caret, type, backspace, bypassdelete, assertcaret, logsel. Launch with -ApplePersistenceIgnoreState YES and recreate the test document fresh each run. The default for live bugs.
4. CGEvent driver — only for paths that must originate as HID events (drag-select, drag-move, autoscroll). TCC decides per session; if input doesn't land after one test click, fall back to level 3 immediately.
5. Instrumented field occurrence — can't trigger it yourself: add the decisive breadcrumb, ask the user to enable verbose tracing, and wait. Days of latency; make sure the next occurrence is decisive.

After a fix: freeze the repro script, run a soak (several trigger cycles in one app run with assertcaret checks), then full swift test.

6. Open-bug inventory

Known open bugs — check here before "discovering" one. Sources: misc/backlog.md (authoritative list) and docs/ROADMAP.md (larger themes, e.g. "TextKit 2 viewport stabilization" is a v1.0.0 item — viewport estimate glitches are a known, partially-mitigated class). All entries below are OPEN as of 2026-07-05.

Do not relabel any of these as fixed without a verified repro flip; no oversell. When you fix one, update misc/backlog.md and this table in the same branch.

7. House rules while debugging

• Never blanket pkill -x edmd. The user's daily-driver app shares the binary name. pgrep -lx edmd + ps -o lstart=,command= -p <pid>, then kill only your own PID (pkill -f EdmundDbg if you launched the debug bundle).
• Do not request Computer Access — Screen Recording and Accessibility are already granted.
• Measure visuals from screencapture pixels (capture by window id, see ARCHITECTURE §8), never from headless layout alone.
• Never mutate storage while hasMarkedText() — including in any diagnostic or repro code you add.
• Never auto-push, PR, or merge. Branch off main per fix; commit small and often.
• Logs in ~/.edmund/logs are app-owned and fair game to read and quote.

Provenance and maintenance

Built 2026-07-05 from: docs/ARCHITECTURE.md (§2, §8, §9), docs/investigations/delete-drift-investigation.md (rounds 1–6), docs/investigations/viewport-glitch-investigation.md, docs/investigations/archives/callout-title-wrap-investigation.md, docs/dev-guides/live-repro-guide.md, misc/backlog.md, docs/ROADMAP.md, and Sources/EdmundCore/TextView/EditorTextView+Diagnostics.swift. Log strings (healing storage edit that bypassed didChangeText, repairing content above origin, recovered stranded desync on focus regain), launch-flag keys, fullLayoutMaxLength, ReproScript commands, the TK1 tripwire, and commit 5bb2b40 were verified against the source tree on that date.

Maintain it like the codebase docs: when a new bug class is understood, add its triage row; when a trap costs real time, add its story to §3; when a backlog bug opens or closes, sync §6 with misc/backlog.md in the same branch. If a row's discriminating check stops matching the code (renamed log string, moved file), fix the row — a stale runbook is worse than none. Deeper mechanism detail belongs in the sibling skills and docs/ investigation files, not here; this file stays a triage surface.