debug

デバッグワークフロースキル

概要

デバッグやリグレッション修正のための、調査を優先するワークフローです。緊急度に応じて、ホットフィックス（迅速で手順を最小限にする）と徹底対応（厳密な調査と完全な RCA ドキュメント）の 2 つのトラックを提供します。

トリガー

次の場合にこのスキルを有効にします。

• ユーザーが debug コマンドを実行した
• ユーザーがバグやリグレッションを報告した
• ユーザーがエラーの調査を必要としている
• ユーザーが「このバグを修正して」などと言った

使い分け： ユーザーが「修正」または「整理」と言った場合、何かが 壊れている（エラー、クラッシュ、誤った動作）なら debug を使用します。コードは 動作している が、構造を改善する必要がある場合は refactor を使用します。

ワークフローの概要

                              debug
                                 │
                            ┌────┴────┐
                            │ Triage  │
                            └────┬────┘
                                 │
               ┌─────────────────┼─────────────────┐
               │                 │                 │
          --hotfix            (default)       --escalate
               │                 │                 │
               ▼                 ▼                 ▼
      ┌────────────────┐  ┌─────────────┐   ┌──────────┐
      │  Hotfix Track  │  │   Thorough  │   │ ideate  │
      │                │  │    Track    │   │ handoff  │
      └────────────────┘  └─────────────┘   └──────────┘

コマンドインターフェース

デバッグワークフローの開始

# Default: thorough track
debug "Description of the bug"

# Fast path: hotfix track
debug --hotfix "Production is down - users can't login"

# Escalate to feature workflow
debug --escalate "This needs architectural changes"

ワークフロー途中のコマンド

# Switch from hotfix to thorough (during investigation)
debug --switch-thorough

# Escalate to ideate (manual handoff)
debug --escalate "Reason for escalation"

# Resume after context compaction
rehydrate <featureId>

トラックの比較

項目	ホットフィックス	徹底対応
緊急度	P0（本番環境が停止）	P1/P2（通常の優先度）
調査	15 分の時間制限あり	時間制限なし
RCA ドキュメント	なし（状態に最小限の情報を記録）	あり（完全な docs/rca/）
ワークツリー	なし（既存の場所で修正）	あり（分離して作業）
レビュー	スモークテストのみ	仕様レビュー
人によるチェックポイント	1（マージ）	1（マージ）

判断手順書

トリアージ段階でトラックを選択する基準を確認するには、判断手順書を照会します。 exarchos_orchestrate({ action: "runbook", id: "triage-decision" })

調査をエスカレーションする基準を確認するには、次を照会します。 exarchos_orchestrate({ action: "runbook", id: "investigation-decision" })

これらの手順書には、トラック選択のための体系的な判断ツリーが記載されています。エージェントは判断ツリーを読み、指針に従います。プラットフォームが分岐を実行することはありません。

debug と refactor の使い分け

指標	debug を使用	refactor を使用
何かが壊れている、または誤動作している	はい	いいえ
コードは動作しているが、煩雑／複雑	いいえ	はい
ユーザーがバグやリグレッションを報告している	はい	いいえ
パフォーマンスの低下	debug から開始（調査）	構造上の問題なら refactor にエスカレーション
「このコードは再編成すべき」	いいえ	はい
本番環境のログにエラーがある	はい	いいえ

目安： 症状（動作すべきものが動作しない）がある場合は debug を使用します。動作しているコードへの 不満（読みづらい、SOLID に違反している、ロジックが重複している）がある場合は refactor を使用します。

ホットフィックトラック

本番環境の問題をできるだけ早く修正します。手順よりも速度を優先します。

HSM フェーズ： triage → investigate（最大 15 分）→ hotfix-implement（ワークツリーなし）→ hotfix-validate → completed

トリアージの指針については、references/triage-questions.md を参照してください。

調査タイマー

1. ホットフィックトラックの選択時に、状態の investigation.startedAt を記録します
2. 主な調査結果が得られるたびに、経過時間を確認します
3. 15 分経過時に investigation.timeout イベントを発行し、ユーザーの確認のために一時停止します
   • 徹底対応トラックに切り替えますか？（はい／いいえ）

フェーズの詳細な手順については、references/hotfix-track.md を参照してください。

徹底対応トラック

適切に調査してバグを修正します。完全な RCA ドキュメントを作成します。

HSM フェーズ： triage → investigate → rca → design → debug-implement（ワークツリー + TDD）→ debug-validate → debug-review → synthesize → completed

フェーズの詳細な手順については、references/thorough-track.md を参照してください。体系的な調査方法については、references/investigation-checklist.md を参照してください。

設計時の制約（Thorough トラック：rca フェーズと design フェーズ）

rca フェーズと design フェーズは、Thorough トラックにおける設計時の段階です。これらのフェーズでは、修正方針を決定する前に、修正に関係するアーキテクチャ上の不変条件に基づく Constraints セクションを提示してください。これは、デバッグの設計時における /ideate のフェーズ 0 に相当し、選択ルールとカタログ登録のゲーティングに同一の単一の信頼できる情報源を使用します。詳しくは @skills/ideate/references/constraint-anchoring.md を参照してください。.exarchos/invariants.md の（cost-of-load: always-load エントリーを）読み込み、Constraints セクションを出力します。カタログ登録によるゲーティング： .exarchos.yml: invariants.catalogs にカタログが登録されていない場合は、Constraints セクションを提示せず、そのまま次に進みます。hotfix トラックでは、この手順を省略します（形式よりスピードを優先します）。

特性テスト（Thorough トラックのみ）

Thorough トラックでバグを修正する前に、特性テストでバグのある動作を記録してください。

1. 修正前： 現在の（バグのある）動作を記録するテストを作成します。バグが存在する状態で PASS する必要があります
2. 修正テストを作成： 正しい動作を記述するテストを作成します。これは FAIL する必要があります（標準的な TDD の RED フェーズです）
3. 修正を適用： 修正を実装します。修正テストは PASS し、特性テストは FAIL する必要があります
4. 検証： 特性テストの失敗によって、バグが実際に修正されたことを確認できます。それでも PASS する場合、修正は根本原因に対処できていません。

hotfix トラックでは必須ではありません。hotfix ではドキュメント作成よりもスピードを優先します。

トラックの切り替え

• Hotfix -> Thorough： 調査タイマーが切れたとき（15 分）。すべての調査結果は保持されます。
• Thorough -> Escalate： 修正にアーキテクチャの変更が必要なとき。ideate に引き継ぎます。

切り替えロジックの詳細は、references/thorough-track.md を参照してください。

自動連鎖の動作

どちらのトラックにも、完了前に人間によるチェックポイントが 1 回あります。

Hotfix の自動連鎖：

triage → investigate → hotfix-implement → [HUMAN: hotfix-validate] → completed
         (auto)        (auto)

Thorough の自動連鎖：

triage → investigate → rca → design → debug-implement → debug-validate → debug-review → [HUMAN: synthesize] → completed
         (auto)        (auto) (auto)   (auto)           (auto)            (auto)

状態管理

デバッグワークフローを初期化します：

action: "init", featureId: "debug-<issue-slug>", workflowType: "debug"

完全なスキーマについては、@skills/debug/references/state-schema.md を参照してください。

フェーズ遷移とガード

各フェーズ遷移には、満たす必要のあるガードがあります。遷移する前に、各ガードの正確な前提条件を @skills/checkpoint/references/phase-transitions.md で確認してください。

スキーマの確認

パラメーターのスキーマには exarchos_workflow({ action: "describe", actions: ["update", "init"] }) を、フェーズ遷移、ガード、プレイブックのガイダンスには exarchos_workflow({ action: "describe", playbook: "debug" }) を使用してください。

統合ポイント

rehydrate との連携

デバッグワークフローは、機能ワークフローと同様に再開します：

rehydrate <featureId>

既存のスキルとの連携

• Thorough トラックのレビュー段階では spec-review スキルを使用します
• PR の作成では synthesis スキルを使用します
• Thorough トラックの実装では git-worktrees スキルを使用します

MCP ワークフロー状態ツールとの連携

以下をサポートするように拡張されています：

• workflowType: "debug" フィールド
• rehydrate <featureId> でデバッグ固有のフェーズを提示（再開時の次の動詞は、再水和ドキュメントの next_actions エンベロープによって決まります）
• セッション開始時に rehydrate <featureId> でデバッグコンテキストを提示（暗黙的なフックはありません）

完了条件

Hotfix の完了

• 根本原因を特定済み（簡潔な特定でも可）
• 最小限の修正を適用済み
• 影響を受けるテストが成功
• フォローアップの RCA タスクを作成済み
• 変更をマージ済み

完了ガードの形式 — completed に遷移する前に exarchos_workflow update で設定してください：

終了経路	ガード	必須の状態
直接プッシュ（PR なし）	fix-verified-directly	resolution: { directPush: true, commitSha: "<sha>" }
検証に合格	validation-passed	validation: { passed: true }
PR 経由	synthesize → completed	prUrl が存在すること

徹底的な完了

• RCA 全文を docs/rca/ に記録します（references/rca-template.md を使用）
• 修正が RCA の調査結果に合致しています
• テストを含む TDD 実装を行います
• 仕様レビューに合格しています
• PR がマージされています

完了ガードの形状 — 徹底トラックは synthesize → completed を経て終了します（ガード：pr-url-exists。state に prUrl が必要です）。

アンチパターン

しないこと	代わりにすること
バグを理解する前にコーディングを始める	まず必ず調査します
徹底トラックで RCA を省略する	将来の学習のために記録します
ホットフィックスの調査に 15 分以上かける	徹底トラックに切り替えます
バグ修正中に機能を追加する	スコープクリープを避け、バグのみを修正します
「修正にすぎない」という理由でテストを省略する	再発を防ぐため、修正にもテストが必要です

トラブルシューティング

MCP ツールの失敗、状態の不整合、調査のタイムアウト、トラック切り替えの問題については、references/troubleshooting.md を参照してください。