mangowhoiscloud 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개 사용:
- Live transcript —
~/.crumb/projects/<id>/sessions/<ulid>/transcript.jsonl직접jq로 query. event kinds / metadata / scores 등 1차 source. - Playwright headless probe —
scripts/diag-output.mjs패턴 (있으면 재사용, 없으면 ad-hoc 작성). page.goto + console + pageerror + network 캡처 + screenshot. - Studio API endpoint —
curl -s http://127.0.0.1:7321/api/{health,doctor, sessions}또는/api/sessions/:id/.... server-side state truth. - Adapter spawn log —
<sessionDir>/agent-workspace/<actor>/spawn-*.log. subprocess의 raw stdout/stderr. - 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 + :239const 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될 가치가 있을 때 작성 위치