troubleshoot-error

いつ使うか（必ず発火する条件）

• ユーザーが「エラーが出た」「動かない」「失敗した」と言ったとき
• analyze / compile / review / render / export の途中で command が non-zero exit したとき
• schema validation が落ちたとき
• ffmpeg / ffprobe / API connector が失敗したとき
• TypeScript compile error や runtime exception で pipeline が止まったとき

前提条件

• まず 失敗した command と stderr をそのまま確認する。要約だけで診断しない
• project artifact が絡む場合、scripts/validate-schemas.ts が canonical validator
• scripts/compile-timeline.ts は compile 前に Gate 1、compile / patch 後に timeline schema を検証する
• scripts/analyze.ts は --skip-stt / --skip-vlm を持つ。GEMINI_API_KEY 未設定は warning + VLM skip であり、常に hard failure ではない
• 詳細な分岐は references/error-catalog.md を参照すること

やること（ステップ）

Step 1: 失敗面を固定する

• 失敗した command、project path、stage、最後に触った artifact、stderr を集める
• ユーザー報告が曖昧なら、最小の再現 command を 1 本だけ実行して failure surface を確定する
• 「どの stage の何が失敗したか」が取れるまでは、広く修正し始めない

Step 2: 最短の deterministic check を走らせる

• artifact 系の failure なら最初にこれを走らせる

npx tsx scripts/validate-schemas.ts projects/<project>

• code / type error ならこれで切り分ける

npx tsc --noEmit

• media / codec / path error なら ffprobe で source を直接確認する
• compile failure なら 01_intent/unresolved_blockers.yaml と validator output を両方見る

Step 3: エラー種別ごとに根因を切る

• schema error: validator の artifact, rule, message, details.instancePath から壊れている field を特定する
• ffmpeg / ffprobe error: source file の存在、権限、codec、02_media/source_map.json の path 解決を確認する
• API error: env var 未設定か、401/403 か、429 か、timeout かを分ける
• compile gate failure: hard blocker なのか、ただの schema invalid なのかを分ける
• TypeScript error: 既存の debt と今回の failure を分け、まず新規 failure を止血する

Step 4: safe な自動回復を試す

• repo 内で deterministic に直せるものは修正して再実行する
• analyze で remote API が不安定なら、要件を壊さない範囲で --skip-vlm / --skip-stt に迂回する
• compile gate が blocker 起因なら、勝手に blocker を消さず、解決済みか temporary assumption が許されているかを確認する
• fix 後は 同じ command を再実行 して recovery を確認する

Step 5: 直らないものは blocker として残す

• bad API key
• sandbox / filesystem permission
• 存在しない source file
• repo 外依存の binary 不足

この種の failure は無理に隠さず、次に必要な action を具体化して返す。

出力 artifact

• canonical な単一 artifact はない
• 必要に応じて壊れていた artifact を修正し、失敗していた stage の出力を再生成する

注意事項

• validate-schemas.ts は violation が 1 件でもあれば exit 1 になる。一方 compile_gate: blocked は Gate 1 blocker 専用の狭い判定
• status: blocker を勝手に resolved に変えない。質問が解決されたか、許可済み assumption がある場合だけ進める
• GEMINI_API_KEY 未設定 warning と、401/403 の invalid key error を混同しない
• TypeScript error では repo 全体の歴史的 debt を一気に直そうとしない。失敗の主因から順に止血する