debugging-playbook — symptom → meaning → discriminating test → action

When a session sees a symptom during a pipeline run, this file routes it. Every entry is backed by a real incident; the discriminating tests exist because the obvious first guess was wrong at least once.

Prime directive: report, don't paper over. For every failure, report four things — (a) which workflow STEP you were in, (b) which browser surface was active, (c) the exact error/status string, (d) whether any file was or was not written to the protected volume. Never improvise an alternate path around a failed gate.

Data hygiene while debugging. The discriminating tests below open real patient documents on the encrypted volume. Run them locally; report only counts, hash prefixes, byte lengths, and status categories. Never paste extracted document text, patient names, or chart contents into a chat reply, a knowledge-base file, a scratch file, or a session log.

Step 0 — universal triage (run before anything else)

1. Which surface? Positively confirm the active browser surface is the attested isolated one. If you cannot confirm it, treat it as the operator's daily browser and STOP (Gate 3 in clinical-change-control).

2. Is the volume genuinely mounted? Before trusting any prior write or making a new one:

   mount | grep -q "<mount-point>" && test -f "<mount-point>/.volume-ok-sentinel" \
     && echo MOUNT_OK || echo MOUNT_FAILED

   MOUNT_FAILED → STOP all writes immediately. Directory-exists is NOT a mount check — an unmounted disk image leaves an ordinary directory stub on the boot volume, and writes there land as unencrypted protected data on local disk.

3. Did anything claim green? If a PASS/saved/OK status is in play, treat it as mechanics-green, not content-correct, until you have opened the actual payload (row 1). This pipeline's worst incident was a double false-PASS.

The symptom table

Detail 1 — payload-reality + byte-identity check (the row-1 test, runnable)

Run in the captured-documents directory on the encrypted volume. Report only counts/prefixes.

# 1. Byte-identity: how many distinct payloads did we actually get?
#    A single dominant hash across all/most files = app-shell fallback until proven otherwise.
shasum -a 256 *.pdf | awk '{print $1}' | sort | uniq -c | sort -rn | head

# 2. PDF magic: a valid capture starts with %PDF- and is >= 1000 bytes.
for f in *.pdf; do printf '%s: %s %s bytes\n' "$f" "$(head -c 5 "$f")" "$(stat -f%z "$f")"; done

# 3. App-shell fingerprint (needs pdftotext): marketing text = NOT a patient document.
pdftotext -f 1 -l 3 "<one-file>.pdf" - | grep -icE "choose the plan|per provider per month|subscription plans|start.?up fees"

# 4. Clinical signal: a real document says patient things.
pdftotext -f 1 -l 3 "<one-file>.pdf" - | grep -icE "patient|date of birth|dob|lab|result|specimen|reference range|assessment|encounter|diagnos|medicat|consent|signed"

Read: test 3 > 0 → app-shell, FAIL. Test 4 = 0 on ≥3 docs → no clinical signal, FAIL. Test 1 showing one hash for everything → FAIL regardless of the others. Gate 0 still applies even when all four pass: open one PDF with your eyes and confirm real clinical content before any PASS is trusted. Mechanics-green ≠ content-correct.

(Treat any auth token embedded in a captured URL as a live credential — never log or paste it; redact on sight.)

Detail 2 — dismissed side-signal = canary

If you catch yourself writing off a small anomaly as "accepted/unavailable," stop — it may share a root cause with the thing you're about to trust.

The incident: during the false-PASS, a document count API returned 401/404 and was waved off — literally encoded in the harness as countApi: { status: "unavailable", accepted: true } — while the manifest went on to report PASS. That dismissed 401/404 shared the auth path that was corrupting document retrieval. The side-signal was the canary; nobody listened, and the run double-PASSed on 14 copies of a marketing page.

Rule: before accepting any green status, list the anomalies you dismissed to get there. Any dismissed anomaly touching the same subsystem (auth, network, session) as the main result invalidates your confidence in the green until explained.

Escalation rules

• A gate says STOP → you stop and report. No alternate path, no "just this once."
• Anything irreversible (archiving a source session, merging a chart update, deleting anything) requires content-validity + identity confirmation AND the operator's explicit go-ahead. When a symptom above is active, the answer is automatically "not yet."
• Before re-fighting a battle ("maybe active refetch works now," "maybe the driver can attach this time"), check the project's failure-archaeology record — if it's marked settled, reopening requires new evidence, not fresh optimism.

Adapting this format

The table format is the product: symptom → what it means → discriminating test → action, one row per incident-backed failure mode. Rules for keeping it honest: (1) no row without a real incident behind it; (2) the discriminating test must cheaply separate the competing explanations — that's what makes it worth writing down; (3) date-stamp volatile facts separately from the rows; (4) a wrong runbook is worse than none — when a re-verification disagrees, fix the row before relying on it.