xs-xangi-kaizen

xangi-kaizen

xangi 上で起きた事象を「事象整理 → ログ調査 → 真因特定 → 横展開 → 修正・報告」の5フェーズで深掘りし、再発防止までやり切る汎用スキル。

スキルの背景・設計思想・参考文献は README.md を参照。

3原則

1. フェーズを飛ばさない — 「事象整理」を飛ばすと検証ポイントを見失う。「横展開」を飛ばすと同じ事故を別箇所で繰り返す
2. 想定で終わらせず証拠で詰める — 「たぶん」を提出物にしない。仮説 → 証拠（git log / reflog / mtime / 履歴出力） → 検証
3. 真因が特定できるまで実装に進まない — 表面的な対症療法は再発の温床
4. コードで推測する前に、事象が出た実際のターンのログを必ず開く — とくに「変な応答が返った」「空だった」「想定と違う出力」系。コードを読んで fallback を見つけると「原因はこれ」と早合点しがちだが、それは「どこで出るか」であって「そのターンで実際に何が起きたか」ではない。先に Phase 2 で対象 bot の session log / tool-trajectory を開き、そのターンの生データを確定してから、コードで「なぜそうなったか」を辿る。

5フェーズのワークフロー

Phase 1: 事象の整理（既知問題チェック含む）

何が起きた / いつ / どこで（チャンネル・対象スキル）。事実を時系列で整理する。

ステップ:

1. 引用メッセージ・チャンネル履歴を取得して事象の輪郭をつかむ

   xangi tool discord_history --count 30
   xangi tool discord_history --channel <ID> --count 50
   

2. 関係するスキル名・cron スケジュール・関連ファイルを箇条書きで把握する
3. 過去事例（KEDB = Known Error Database）を必ず確認 — [NOTES_DIR] の過去 xangi-kaizen ノートを事象キーワードで grep

   # xangi-kaizen タグの全事例
   grep -rl '#xangi-kaizen' [NOTES_DIR] | sort
   
   # 対象スキル名・キーワードで絞り込み
   grep -rl '#<対象スキル名>' [NOTES_DIR]
   grep -rl 'state\|cron\|<キーワード>' [NOTES_DIR]/*xangi-kaizen* 2>/dev/null
   

   ヒットした事例は中身を読む。同じパターンなら「対策」「教訓」をそのまま適用できる。未知なら次フェーズへ。

Phase 2: ログ調査

複数のソースを横断的に追う。一つの観点で結論を出さない。

ステップ 0（重要）: 調査対象 bot の workspace を特定する。 xangi は bot ごとに別 workspace・別プロセスで動く構成を取りうる。複数 bot を運用している場合、手元の workspace だけを見ても対象 bot の事象は写っていないことがある。

# Docker 運用の場合: bot がどのコンテナか確認
docker ps --format '{{.Names}}\t{{.Image}}'

# コンテナの workspace マウント元を確認
docker inspect <container> --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{println}}{{end}}' | grep '/workspace'

特定した <bot-workspace> 配下の logs/sessions/ と logs/tool-trajectory/ を見る。環境変数やチャンネル割り当ては各 bot の .env で確認する。

観点	コマンド/対象
state ファイル	[STATE_DIR]/*_state.json、references/*_last_check.json 等の中身と stat -c "%y %n"
git 履歴	git log -p --all -- <path>、git show <commit>:<path>
git reflog	git reflog --since=<時刻>（ブランチ切替・rebase・reset の追跡）
cron / schedule	xangi tool schedule_list 2>&1 | grep -B2 -A3 <キーワード>
セッションログ（生応答）	対象 bot の <bot-workspace>/logs/sessions/*.jsonl。事象の出たチャンネル ID で grep -rl <channelId> → 該当ファイルの当該ターンを開き、assistant result を確認
tool-trajectory ログ	<bot-workspace>/logs/tool-trajectory/*.jsonl。tool search / loop / drift / stream buffer / cache などのイベントが時系列で残る
該当スクリプト/コード	skills/<name>/scripts/、または対象リポのソース。ログで事象を確定した後に「なぜそうなるか」を辿る
投稿履歴	xangi tool discord_history --channel <ID> --count 30