crumb-deep-dive

# 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): ```bash 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될 가치가 있을 때 작성 위치