loop-diagnosis

ループの診断

停滞したエージェントのコーディングループを診断し、修正します。このスキルでは、診断 CLI、よくある障害モード、サイレントな停滞を防ぐオブザーバビリティのパターンについて説明します。

クイックコマンド

# Diagnose all active loops at once
joelclaw loop diagnose all -c

# Diagnose a specific loop
joelclaw loop diagnose <loop-id> -c

# Diagnose AND auto-fix
joelclaw loop diagnose all -c --fix

# Full JSON output (for detailed inspection)
joelclaw loop diagnose <loop-id>

診断で確認される内容

diagnose コマンドでは、次の 6 項目を順に確認します。

1. Redis の状態 — PRD のストーリー（合格／スキップ／保留中）、進捗エントリー、アクティブなクレーム
2. ワークツリー — 存在するか？コミットはあるか？未コミットの変更はあるか？.out ファイルはあるか？
3. Inngest の実行 — 実行中／失敗した agent-loop-* 関数、最近の計画実行
4. エージェントプロセス — claude/codex プロセスがまだ動作しているか？
5. ワーカーの健全性 — localhost:3111/api/inngest の function_count
6. 診断 — 上記をパターン照合して根本原因を特定

障害モードと修正方法

診断	根本原因	自動修正
CHAIN_BROKEN	Judge は story.passed を送信しましたが、plan が受信できませんでした。イベントが転送中に失われています。	agent/loop.story.passed を再送信 → plan が次のストーリーを選択
ORPHANED_CLAIM	ストーリーがイベントによってクレームされましたが、エージェントが終了し、アクティブな Inngest 実行もありません。	クレームをクリアして、plan イベントを再送信
STUCK_RUN	Inngest の実行は RUNNING とマークされていますが、エージェントプロセスは終了しています。実行は完了しません。	クレームをクリアして再送信（Inngest ダッシュボードで手動による実行のキャンセルが必要な場合があります）
WORKER_UNHEALTHY	ワーカーが想定より少ない関数を登録しています。インポートの欠落またはクラッシュループが原因です。	k8s の system-bus-worker デプロイを再起動
NO_PRD	ループの PRD が Redis にありません。削除されたか、作成されていません。	なし — 新しいループを開始
COMPLETE	すべてのストーリーが合格またはスキップ済みです。対応は不要です。	なし — joelclaw loop nuke dead を実行してクリーンアップ

使用する場面（他のスキルとの使い分け）

• loop-diagnosis → ループが停止／停滞しており、原因を特定して修正する必要がある場合
• loop-nanny → ループが実行中で、進捗を監視し、終了後にクリーンアップする必要がある場合
• agent-loop → 新しいループを開始する必要がある場合

イベントチェーン

チェーンを理解しておくと、どこで問題が起きたかを診断しやすくなります。

agent/loop.started
  → plan (picks story, dispatches test-writer)
    → agent/loop.story.dispatched
      → test-writer (writes acceptance tests)
        → agent/loop.tests.written
          → implement (codex/claude writes code)
            → agent/loop.story.implemented
              → review (runs tests, typecheck, claude review)
                → agent/loop.story.reviewed
                  → judge (pass/fail/retry decision)
                    → agent/loop.story.passed  ←── feeds back to plan
                    → agent/loop.story.failed  ←── feeds back to plan
                    → agent/loop.story.retry   ←── feeds back to implement

最もよくある障害箇所: judge → plan。agent/loop.story.passed イベントは発火しますが、plan が受信できません。これは次の場合に発生します。

• イベント発生中に Inngest が再起動している
• judge と plan の間にワーカーが再起動した
• k8s の Pod 再起動によってイベントが失われた

オブザーバビリティのパターン

パッシブ：失敗イベント

すべてのループ関数で、onFailure ハンドラーを介して失敗イベントを発行する必要があります。これらのハンドラーは agent/loop.function.failed を発火し、標準の OTel/Inngest イベントサーフェスを通じて確認できる必要があります。

アクティブ：ウォッチドッグ（今後の予定）

定期的に実行される Inngest 関数（system/loop-watchdog）で、次の処理を行います。

1. Redis 内で保留中のストーリーがあるすべてのループをスキャンする
2. 過去 10 分間にイベントが発行されたかどうかを確認する
3. 発行されていない場合 → diagnose と修正を自動実行する
4. 動作またはオペレーターの操作に変更があった場合に限り、OTel イベントを発行し、永続的な Brain レシートを書き込む

手動：診断セッション

エージェントが手動でループをデバッグする必要がある場合は、次の手順に従います。

# 1. Quick overview
joelclaw loop diagnose all -c

# 2. If fix needed
joelclaw loop diagnose all -c --fix

# 3. Verify fix worked (wait ~30s for plan to fire)
joelclaw loop status <loop-id> -c

# 4. If still stuck, check worker
curl -s localhost:3111/api/inngest | python3 -c "import json,sys; print(json.load(sys.stdin)['function_count'])"

# 5. Nuclear option: full restart
joelclaw loop restart <loop-id>

ループのレジリエンスを高める

多くの停滞の根本原因は、judge→plan チェーンでイベントが失われることです。次の解決策を実装中です。

1. onFailure ハンドラー — すべての関数に追加し、失敗を記録して診断イベントを発行する
2. ループウォッチドッグ — サイレントな停滞を定期的に確認する
3. content-sync のデバウンス — イベントの集中によってループイベントが押し出されるのを防ぐ
4. バックフィルのシングルトン化 — ループ実行中のリソース競合を防ぐ

関連項目

• agent-loop スキル — ループの開始
• loop-nanny スキル — 監視とクリーンアップ
• joelclaw スキル — CLI の全リファレンス
• ADR-0028 — 信頼性のパターン