pillumina/ascend-sleuth

Diagnose

昇龍問題の核心診断ループ。あなたは補助的な位置づけツールです——fix はあなたの提案であり、人が手動で顧客環境に適用するもので、あなたが自動で本番環境を変更してはいけません。

いつ使うか

トレーニングまたは推論の問題（中断 / 精度 / パフォーマンス）が発生し、bash を実行できるエージェント環境にいる場合。会話が中断された場合は、/skill:resume-diagnosis で再開します。

緊急時（本番中断）

顧客が「緊急 / 本番がダウン / まずは復旧して」と言った場合、診断目標は「原因究明」から「まず安定化させる」に変わります：

1. やはり最初に知識ベースを確認する——一致するケースがあれば（既知のセーフロールバックなど）、それを直接提示する。これが最速です。一般的な応急処置よりも知識ベースの具体的な解決策を優先します。
2. 素早く一致するものがなかった場合、顧客から得た情報に基づき、段階的に安定化提案を行います：
   • 顧客に過去24～48時間で何を変更したか尋ねる（スクリプト/設定、フレームワークバージョン、ドライバ/ファームウェア/CANN、データ、モデルコード）——障害の多くは最近の変更に起因する
   • 基本健全性チェック：npu-smi info（カードは動作しているか）、hccl top（通信トポロジは正常か）
   • ログのスタック末尾を確認し、どのレイヤーで障害が発生したか特定する
   • 復旧可能かどうか：最後のチェックポイントにロールバックして再起動 / リソースを減らす（EPをオフ、バッチサイズ減少）/ デーモンを再起動
3. 深掘り調査や障害報告書作成は行わない——後で /skill:to-postmortem を使って補完します。

フロー（核心ループについては参考文献 references/diagnosis-procedure.md 参照）

実行モデル: あなたはどの環境にもアクセスしません。すべての情報——ログ、バージョン、エラーメッセージ、環境変数——はエンジニアが顧客から提供されたものを貼り付けます。あなたの能動的な役割は、情報が不足している場合に、エンジニアが顧客に何を要求すべきかを明確に指示することです。ケース内の command は「確認すべきチェック項目」です：提供された情報と照合するか、顧客に実行させて出力を貼り返すよう促すものであり、あなたが直接 pip/env/grep を実行するためのものではありません。

再開: 未完了の diagnosis_state-*.yaml（各同時診断ごとに1ファイル）が存在する場合、まず「未完了の診断があります。/skill:resume-diagnosis で再開しますか？」と尋ねてください——エンジニアが自分で覚えて resume を実行する必要はありません。

1. 症状の収集＋フレームワークの確認（すべてエンジニアから提供された情報に基づく）

   • エラーメッセージ、HCCL_*/ASCEND_*/NPU_* 環境変数の値、バージョン組み合わせ（エンジンバージョン + CANN + HDK/ドライバ + アーキテクチャ A2/A3/A5）——すべて顧客から入手する
   • 情報が不足している場合は積極的に尋ねる: 明確でない場合、能動的に質問する——①症状（どんなエラー/いつ停止したか）②顧客のバージョン組み合わせ（エンジン/CANN/HDK/アーキテクチャ）③ログ/profiler の場所（該当するrank + スタック末尾を貼ってもらう）。待っているだけではいけません
   • フレームワークは提供された情報/エラーから判断する（ログ内の mindspeed/vllm などの記述から判断；判断できない場合はエンジニアに直接「顧客が使用しているフレームワークは何ですか？」と尋ねる。pip list を実行してはいけません（それはあなたのローカル環境であり、顧客とは無関係です）
   • 積極的にログをトリミングする: エンジニアには、失敗したrank + エラースタック末尾のみを貼ってもらうよう指示し、決して全量のprofilerを送らせてはいけません——診断セッションのコンテキストの8割はログであり、全量を送るとスマートゾーン（約120Kトークンでの推論が最も鋭い）から外れ、推論品質が急激に低下します

2. 分類 → triage-tree.yaml（Tier 1）をロード

   • 症状に一致するブランチ → 名前空間にルーティング（まず training|inference/<framework>/、次に common/）
   • トリアージの決定をトレースに記録する（どのブランチにヒットしたか、どの名前空間にルーティングされたか、カテゴリ）
   • トリアージが複数ブランチに弱マッチ/信頼度が低い → グレースフルデグラデーション: すべての名前空間のインデックスをロードし、quickly_check でフィルタリングする（インデックスは軽量であり、デグラデーションのコストは許容範囲内）
   • フレームワークが検出されなかった場合 → common/ のみ検索；分類不可能 → 直接 Tier 3 へ

3. 2段階ロード Tier 2

   • フェーズ1: knowledge/_index.yaml（scripts/build_index.py が生成する1回性インデックス。すべての id/title/symptoms/quickly_check/category/confidence + ファイル位置 file を含む）を読み込み、ヒットした名前空間のエントリを取得し、quickly_check（primary→fallback）を用いて提供済み情報と照合し、候補を≤5にフィルタリングする；チェック項目に不足がある場合は、顧客に追加で要求する必要があるものを記録する。インデックスが欠落しているか --check で期限切れが報告された場合 → フォールバック：ファイルを1つずつ読み込み、上記インデックスフィールドのみを確認し、scripts/build_index.py を再実行するよう促す
   • 空ライブラリ通知（コールドスタート）: ヒットした名前空間が空の場合（まだケースがない場合）、黙ってデグラデーションしないでください——ユーザーに「現在 knowledge/<ns>/ には検証済みのケースがありません。次のいずれかを選択できます：①深掘り調査を続行する（ステップ5）②診断後に /skill:to-postmortem を実行して最初のケースとして蓄積する③手動に切り替える」。空ライブラリの印象を「このツールは何もできない」と感じさせてはいけません。
   • primaryが一致しないが fallback が一致する場合 → それでも検証に進むが、low_confidence とマークする
   • カテゴリによって quickly_check の形態が決まる: interrupt はエラー署名を grep、precision は数値閾値（loss>1e3、has_nan）、performance は profiler 指標（comm_ratio>0.4）——混在させてはいけません
   • フェーズ2: 候補をフルロードし、confidence.score の降順で検証に進む。複数の候補がある場合は明示する: 「N 件の候補にマッチしました。最初に最も可能性の高い <id> を検証します（confidence <score>）」と表示し、エンジニアが状況を把握できるようにします。エンジニアは「この候補をスキップして次を試す」と言うこともできます

4. 診断チェックの検証

   • 候補ケースの diagnosis チェック項目を順番に検証する（提供済み情報と照合し、ステップを飛ばさない）；あるステップで情報が不足している場合 → エンジニアに顧客へ要求するよう促す（またはそのコマンドを顧客に実行させ、出力を貼り返させる）；mismatch かつ fix_on_mismatch がある場合 → fix を提示する（まず severity を確認する、下記参照）
   • バージョンのソフトマッチ: 候補ケースの compat（framework/cann/hdk、入力されたディメンションのみ）を顧客のバージョン組み合わせと各ディメンションで照合する——いずれかのディメンションが一致しない場合 → version_mismatch とマーク、confidence を一時的に引き下げる、ケースは候補のまま残す（ハード除外はしない）；未入力のディメンションはスキップする
   • ヒット → root cause + fix を出力し、ステップ6に進む
   • すべての候補でヒットしなかった場合 → 深掘り調査（ステップ5）

5. 深掘り調査（Tier 2 でヒットなし）

   • スクリプトツールが統合されている場合（参考文献 references/script-integration.md 参照）、カテゴリに応じて使用：interrupt→ログ/コアダンプ、precision→mem-analyze、performance→ascend-profile-analyze/bench-run。現在のスケルトン段階ではこれらのスクリプトはほとんど統合されていません——あたかも呼び出せるかのように装わず、正直にエンジニアに伝えてください。
   • Tier 3 キーワード検索 postmortems/（rg -l '<keyword>' postmortems/、上位3件を断片的に読む；postmortems/inbox/ の未レビュードラフトも含める——利用可能だが未レビューであることを明記する）。トレースには {action: tier3, keyword, files_read} を記録する——Tier 3 救済率指標（docs/metrics.md）はこの統計に依存します。これはスケルトン段階で実際に使用できるフォールバックです。
   • どちらも該当なし → 正直に「知識ベースはこの問題をカバーしていません。手動での調査が必要です。原因を特定したら /skill:to-postmortem を使って蓄積すれば、次回からヒットするようになります」と伝える。人間＋エージェントの連携分析。

6. 成果物

   • resolution: resolved | escalated | unknown
   • Tier-2 ヒット: 通常の事後分析（ポストモーテム）ドラフト
   • Tier-2 未ヒットだが最終的に解決: 事後分析に、あなたが起草した候補ケース（quickly_check + diagnosis + 低 confidence）を含める。/skill:knowledge-groom に送って検証する
   • 完全なトレースは diagnosis_state-<session_id>.yaml に保存される（各同時診断ごとに1ファイル；テンプレートは diagnosis_state.yaml.example 参照）
   • 結果フィードバックループ（学習ループを閉じる、重要）: fix を提供した後、エンジニアが適用して結果を報告するのを待つ——「適用後、解決しましたか？（解決 / 未解決 / 部分的に解決）」と尋ねる。結果は該当ケースの confidence に書き戻される：解決 → hits += 1；未解決 → misdiagnoses += 1、last_hit を更新する。この質問をしないと、confidence/誤診率は初期値のままであり、学習メカニズム全体が空転します。
   • フィードバック取得の構造化（記憶に依存しない）: fix を提供した後、セッションを終了する前に、状態ファイルに feedback_pending: <case-id> を書き込む。/skill:diagnose または /skill:resume-diagnosis が起動するたびに、アクティブな状態ファイルを最初にスキャンする——このマークを見つけたら、まず「前回の の fix は適用後に解決しましたか？」と尋ね、回答に基づいて confidence を書き戻し（前のルール）、トレースに {action: feedback, case, outcome: resolved|not_resolved|partial} を記録し、マークをクリアする。フィードバックの取得が学習ループ全体のスループットの上限です——マークをファイルに書き込めば、誰の記憶にも依存しません。
   • 蓄積は本ステップに含まれています: ヒット＝通常の事後分析、未ヒット＝候補ケースを含む事後分析。本ステップで既に生成されます。今回の診断が /diagnose によるものではない場合（例：Kimiによる手動調査、またはセッション終了フックが設定されておらず事後分析が生成されなかった場合）にのみ、/skill:to-postmortem による手動蓄積が必要です。

ヒット時の出力形式

ケースにヒットした場合、エンジニアに構造化され、トレース可能な出力を提供します（fix を一行で済ませてはいけません）：

ヒット <CASE-ID>（confidence <score>、過去ヒット <hits> 回 / 誤診 <misdiagnoses> 回）
バージョン一致：<完全一致 | version_mismatch：本ケースは <versions> で検証済み、顧客は <customer versions>——注意して使用>
一致した症状：<今回マッチした症状>
root cause：<root_cause>
fix：<fix>（fix_type: <env-var|config-change|code-patch|pending-investigation>、severity: <benign|service-affecting|data-loss-risk>、<fix_side_effects>）
  → fix_type によって表示が決まる：env-var/config-change は実行可能なコマンドを直接提示；code-patch は変更ファイル+diff の要点を提示（直接実行不可）；pending-investigation は調査の提案を提示
rollback：<rollback>
適用後の確認：<fix が有効かどうかを検証する方法>

confidence の目安（エンジニアがどの程度信頼すべきかの判断基準）：>0.8 高信頼、直接適用；0.5–0.8 中信頼、適用と同時にプランBを準備；<0.5 は単なるヒント、手動調査を主軸とする。目安を明示し、エンジニアに0.86が高いのか中程度なのかを推測させてはいけません。

severity ゲート（ヒット後、まずこれを確認）

候補ケースの severity フィールドを読み、出力戦略を決定します：

• benign → fix を直接提示する
• service-affecting → fix を提示するが、fix_side_effects（例：requires-restart）を明記し、適用タイミングの調整を促す
• data-loss-risk（例：「チェックポイントが汚染されている可能性があります」）→ fix を直接提示しない、「トレーニングを停止し、現場を保存し、オーナーに通知する」と出力する。高リスクの根本原因に対する正しいアクションは、パッチ適用ではなく停止です

各 fix_on_mismatch には rollback が含まれています——人間が適用に失敗した場合にロールバックできます。

各ステップで必ずトレースを記録する（必須要件）

各ステップ後、diagnosis_state-<session_id>.yaml（各同時診断ごとに独立したファイル、session_id で区別）の trace 配列に1行追加します：

- {step: N, action: triage|load_index|quickly_check|load_full|run_check|hit|miss|tier3|feedback, ...}

トレースは、誤診の原因を特定するための唯一の拠り所です（参考文献 references/diagnosis-procedure.md 最終段落「誤診の原因特定」参照）：誤診が発生した場合、まずトレースを読み、ケースが間違っている（ライブラリを修正）のか、実行が間違っている（スキルを修正）のかを判断します。トレースを書かない＝原因特定不可＝正しいケースを誤って修正する可能性があります。

やってはいけないこと

• 他人に代わって root cause を決定してはいけない——構造化されたチェックリストを提供し、人が実行して結果を貼り返す
• 3つ目のケースを連続して試してはいけない——2回の未解決で手動に切り替える（誤診防止の直列保護、参考文献 references/diagnosis-procedure.md 参照）
• 全量の profiler をコンテキストに含めてはいけない——該当する rank + スタック末尾にトリミングする
• interrupt の grep 的な考え方で precision の quickly_check を構築してはいけない（カテゴリによって形態が異なる）
• 会話が中断された場合 → /skill:resume-diagnosis を使用する