the-ready

routine-investigate

失敗した週次収集回の原因を調べ、小さく直せるものだけを直す手順。GitHub Actions の self-hosted runner から claude -p の引数として起動される。直せないときは診断だけを書いて終える。

the-ready 1 Updated 4w ago
GitHub

Install

npx skillscat add the-ready/player-one/routine-investigate

Install via the SkillsCat registry.

SKILL.md

週次収集の失敗を調べる

今回の実行

  • 今日: !date '+%Y-%m-%d(%a)'
  • 調べる対象: 環境変数 FAILED_RUN_URL の実行(FAILED_RUN_CONCLUSION がその結末)

不変規則(システムプロンプト)が最優先である。 この手順と食い違ったらそちらに従う。
とくに「git に触らない」「検査を弱めない」「3ファイル・80行まで」「data/ を書き換えない」は
ここで繰り返さないが、一度も緩まない。

進め方

1. 何が落ちたのかを特定する

ls -t .claude/logs/routine_*.log | head -3

直近のログの末尾から読む。全文を読まない(長い回は数万行ある)。

tail -n 200 .claude/logs/routine_$(date '+%Y-%m-%d').log

見るべきは次の3つ。

  • 最後に成功した工程はどれか(どこまで進んで落ちたか)
  • エラーメッセージの原文(要約しない。あとで再現に使う)
  • 終了工程まで届いていたか(届いていれば、収集そのものは機能していた)

2. 原因を分類する

よくある順に並べてある。上の2つは、このルーチンでは直せない。

兆候 分類 対応
認証 401 /login OAuth トークン失効 直せない。報告に書いて終える
usage limit 利用上限、経過時間に対して不自然に早い終了 アカウント利用上限 直せない。報告に書いて終える
Traceback が tools/ のどれかを指す 道具の不具合 直す対象。3へ
validate_data.py が ERROR を出している データの不整合 data/ は触れない。報告に書いて終える
収集先サイトの構造変更(抽出が0件、想定した要素が無い) 収集規則のずれ tools/fetch_page.py 側なら直す対象。SKILL.md の規則の変更は人に渡す
fetch_gate robots による拒否 相手側の都合 直さない。報告に書いて終える
ネットワークのタイムアウト、単発の失敗 一時的 直さない。報告に書いて終える

迷ったら「直せない」側に倒す。 診断だけを返すことは、このルーチンの正常な結果である。

3. 再現する

直す前に、必ず手元で落ちることを確かめる。ほとんどの場合これで足りる。

python3 tools/run_all_tests.py

これで落ちないなら、落ちたのはテストが見ていない経路である。
その場合はログのエラーを起こす最小のコマンドを自分で組み立てて示す。
再現できなければ直さない。 再現手段を報告に書いて終える。

4. 直す

原因そのものを直す。症状を隠さない。

直したら、必ず通す。

python3 tools/run_all_tests.py

これが通らない限り、スクリプトは push しない(通っても、差分が規則に触れていれば push しない)。

5. 報告を書く

最後に必ず次の4点を、この順で出力する。 スクリプトがこれをそのまま Issue に載せる。

## 原因
(何が、なぜ落ちたか。推定なら「推定」と書く)

## 再現
(実際に叩いたコマンドと、その結果。再現できなかったならそう書く)

## 直した内容
(触ったファイルと、何を変えたか。直していないなら「直していない」と書き、その理由を添える)

## ゲートの結果
(run_all_tests.py の結果。落ちたテスト名があれば列挙する)

push されるかどうかを自分で判断しない。それはスクリプトの仕事である。
あなたの仕事は、原因を突き止めて報告を残すことと、直せると確信したものだけを直すことの2つに限られる。