crumb-deep-dive

name	crumb-deep-dive
description	>-

Crumb Deep-Dive Ritual (4-단계 스캐폴드)

Origin: 2026-05-05 사용자 directive — "추정하지 말고 로그 혹은 이벤트와 같은 관측성 데이터로 원인 확정해" + "이 절차를 스캐폴드로 굳히고". Live smoke 01KQVSE9PC에서 Studio Output blackbox 진단을 Playwright headless probe로 정확히 잡은 것이 first canonical example.

4 stages — every feature/fix follows this order

Stage 1 — Implement (narrow PR)

• 한 PR = 단일 의도 (1-3 commits, 100-300 LOC). PR-Bundle은 architectural 관련 의도 하나로 한정.
• Pre-PR Quality Gate: npm run verify (lint:all + typecheck + format:check + zod:check-envelope + check-lockfile + test + build).
• Sandwich 파일 변경 시 npm run sandwich:update-hashes.
• Lockfile platform-deps 검증: node scripts/check-lockfile-platform-deps.mjs (macOS @emnapi pruning 자주 재발).
• Commit: imperative mood + 변경 의도 + 1-line 왜 지금 명시.

Stage 2 — Verify with raw data (NOT 추정)

선택 가능한 verification surface 5가지 — 항상 ≥1개 사용:

1. Live transcript — ~/.crumb/projects/<id>/sessions/<ulid>/transcript.jsonl 직접 jq로 query. event kinds / metadata / scores 등 1차 source.
2. Playwright headless probe — scripts/diag-output.mjs 패턴 (있으면 재사용, 없으면 ad-hoc 작성). page.goto + console + pageerror + network 캡처 + screenshot.
3. Studio API endpoint — curl -s http://127.0.0.1:7321/api/{health,doctor, sessions} 또는 /api/sessions/:id/.... server-side state truth.
4. Adapter spawn log — <sessionDir>/agent-workspace/<actor>/spawn-*.log. subprocess의 raw stdout/stderr.
5. External API/docs — Vertex AI / Replicate / ElevenLabs official model docs, GitHub issues. WebFetch로 canonical answer.

하지 말 것:

• "아마 ~ 때문일 겁니다" — guesswork 금지
• "보통 ~ 입니다" — 일반화 금지
• 사용자 의도 추측 — 직접 묻기

해야 할 것:

• 데이터 location 명시 (file path + line number 또는 API endpoint + jq path)
• 결정적 evidence chain — A → B → C 사실 sequence
• 여러 evidence가 같은 결론을 가리키면 명시 ("transcript + Playwright + spawn log 3 source 모두 X를 지목")

Stage 3 — Root cause report

Format (≤500 words, markdown):

## 관측성 데이터로 확정 — <증상>

### Evidence
- <source 1>: <data citation> → <fact 1>
- <source 2>: <data citation> → <fact 2>
- ...

### Root cause
<file:line + 1-line 인과 chain>

### Implication
<system invariants 위배 여부 / Karpathy P# 위배 여부 / 기존 PR과의
관계 — 가설 부정된 PR이 있으면 명시>

### Improvement options
| 옵션 | LOC | trade-off |
| A | ~N | ... |
| B | ~M | ... |
| 추천 | ★ <옵션> + 이유 |

필수 요소:

• file:line 또는 endpoint 정확 인용
• 가설 / 부정된 가설 명시 (예: "iframe sandbox 차단 가설 → Playwright 200 OK로 폐기")
• Improvement는 옵션 매트릭스 + 추천 형태 — 사용자 결정권 보존

Stage 4 — Improvement PR (별개)

• Stage 3 보고를 그대로 PR description의 "Why" section에 인용
• Stage 1 PR과 다른 branch + 다른 PR number. 같은 PR에 묶지 않음 (사용자가 Stage 3 보고 보고 결정 후 진행).
• 작은 단위로 — 하나의 root cause만 fix.
• 머지 후 main에 반영되면 즉시 Stage 1으로 ritual 다시 시작 가능 (또는 다른 feature로 이동).

When to skip the ritual

• Trivial change (단일 file rename / typo / format-only): Stage 2-3 skip, 바로 commit.
• Reverting a regression when the regression cause is already documented in prior commit history / PR description: 그 인용으로 Stage 3 대체 가능.
• Pure refactor with no behavior change: 기존 tests가 Stage 2 역할 → 사용자가 별도 보고 요구 시만 Stage 3.

그 외 모든 feature / bug fix: 4-stage 강제.

Examples

Example 1 — Studio Output blackbox (2026-05-05, canonical)

• Stage 1: 사용자가 "Output 여전히 블랙박스" 보고. 추정 옵션 5개 (CDN 차단, WebGL fail, JS error, sandbox CSP, canvas size 0).
• Stage 2: scripts/diag-output.mjs 작성. Playwright headless 9 modules 로드 + console + pageerror + canvas 캡처. 결과: 모든 200 OK / pageerror = "Identifier 'remaining' has already been declared" 1건 / canvas 미생성.
• Stage 3: file:line 정확 인용 — artifacts/game/src/scenes/GameScene.js: 231 + :239 const remaining 중복. 5개 추정 옵션 중 4개 데이터로 폐기 (CDN 200 OK / WebGL warning만 / sandbox attr 무관 / canvas 0이 아니라 미생성). Root cause = builder LLM 작성 실수. Improvement 옵션 A (손수정), B (재빌드), C (qa-runner spec-driven boot predicate으로 미리 잡기 — PR #231 적용됨, follow-up).
• Stage 4: PR #233 (Output console rail) — 같은 case가 다음에 발생하면 Studio가 즉시 surface하도록 iframe contentWindow.console hooking.

Example 2 — Provider mix 0% on google/openai (2026-05-05)

• Stage 1: 사용자가 "google/openai 0% 가 잘못됨" 보고.
• Stage 2: transcript jq query — metadata.provider 별 event count + tokens. 결과: google 5 events / step.research.video에 27,902 tokens_in stamped / agent.stop에는 null.
• Stage 3: ServiceMap.tsx:154 computeProviderMix가 agent.stop 만 sum 하는 게 root cause. gemini-sdk adapter도 SpawnResult.usage 미반환. 두 곳 fix.
• Stage 4: PR #233 (d) — ServiceMap.tsx + gemini-sdk.ts 동시 수정.

Tooling shortcut

자주 쓰는 jq pattern (transcript inspection):

TX=~/.crumb/projects/<id>/sessions/<ulid>/transcript.jsonl

# Per-kind count
jq -r '.kind' "$TX" | sort | uniq -c | sort -rn

# Per-provider events
jq -r '.metadata.provider // "(none)"' "$TX" | sort | uniq -c

# Last N events with from/kind/body
tail -10 "$TX" | jq -r '"\(.ts | split("T")[1] | split(".")[0]) [\(.from)] \(.kind) | \(.body // "" | .[0:120])"'

# Find events with token usage
jq -r 'select(.metadata.tokens_in or .metadata.tokens_out) | {kind, from, in: .metadata.tokens_in, out: .metadata.tokens_out}' "$TX"

# Verifier verdict trail
jq -r 'select(.kind=="judge.score" or .kind=="verify.result" or .kind=="handoff.rollback") | {ts, body: (.body | .[0:150])}' "$TX"

자주 쓰는 Playwright probe (scripts/diag-output.mjs): page load + console + pageerror + network + canvas state + screenshot.

References

• AGENTS.md §Architecture invariants — Stage 2-3는 invariant 위배 여부 체크 하는 자리
• .skills/anti-deception-checklist/SKILL.md (gitignored) — Stage 3에서 "fake success" / "test deletion" 등 anti-pattern 회피 체크리스트
• .skills/agent-ops-debugging/SKILL.md — multi-agent system root cause 분석 패턴 (Safe Default anti-pattern, ContextVar DI 등)
• wiki/synthesis/ — Stage 3 보고가 wiki page로 promote될 가치가 있을 때 작성 위치