Catchup

---
name: catchup
description: 「これどうなってたっけ」への答え。並行作業から戻ったとき、1 件の PR / issue（番号か URL）・ブランチ名・今のブランチ（引数なし）・手元の commit・会話の中の話題について、前回自分が触ってから何が起きたかを 1 枚の HTML に描き、どこで止まっていたかを思い出すために使う。番号・URL・ブランチ名なら該当ブランチへ移る（追跡ファイルに未コミットが有れば移らない）。/catchup setup で VS Code で見る準備をする。open 全件の棚卸しは /whose-turn。
allowed-tools: Bash, Read, Write
---

# /catchup

1 件の PR・issue・ブランチ・commit・会話の話題について、「前回私が触ってから何が起きたか」を 1 枚の HTML のページに描く。「私」は gh（GitHub の CLI）の認証ユーザで、ページを読む人。ページには、誰のターンか・次の一手・止めているもの、前回からのターンの動き、その件が何のために・何を・どう変えるかの説明と図、指摘・CI・差分が有れば全部載る。端末にはページの path と 1 行の要約だけを返す（手順 10）。

呼び方は `/catchup [対象] [焦点]`。

- 対象は 1 つ。番号・URL・ブランチ名・commit（範囲 `A..B` も）・会話の話題・`setup` のどれか。無ければ今のブランチ（`this`）。
- 焦点は 0〜3 語。`指摘`（未解決のスレッド）・`地図`（変更の地図）・`CI` で、英語の `threads`・`map`・`ci` も同じ。付けると、ページの後ろのセクションをその語の物だけに絞る。既定は全部。

機械は `bash "${CLAUDE_PLUGIN_ROOT}/scripts/run-python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/catchup.py"` で呼ぶ（以下 `catchup.py`。`python3` に替えて打たない）。機械は事実を出し、判断しない。判断して文を書くのはあなた（AI）。

## 守ること

1. **事実は機械から取り、確かめた中身で書く。** 機械の出力に無いことを断定しない。確かめていないことには「（未確認）」と付ける。日付と件数は機械の数字を使う。描く材料の JSON を手で直さない（事実が違えば機械を呼び直す）。機械が gh の失敗で止まったら、そこで止まって訳を返す。
2. **手元のブランチを変えるのは機械だけ。** stash・commit・`git switch`・`git fetch` を自分で打たない。checkout は別のセッションと共有されていることがあり、未コミットの変更は誰かが編集中かもしれない。
3. **読み手ごとに書き分け、良し悪しを判定しない。** ページの上（いまのターン・前回から）は、戻ってきた私が 5 秒で読める短い文にする。「この PR がすること」は、初めて見るエンジニアが仕組みと理由を掴める詳しい説明にする。説明は理解のためで、レビューではない。求められていない欠陥探しへ広げない。
4. **端末には機械が出す 2 行だけを返し、問いで返さない。** 番号でない語は会話の話題として描く。問いで返すのは、手元にも会話にも対象が無いときだけ。
5. **1 つの会話の中で順に回す。** subagent・Agent・Workflow を立てない（起動に分単位かかり、待ち方を誤ると 10 分止まる）。`gh` は Bash で 1 本ずつ打つ。例外は、説明の「一般の構造との違い」のために別のエージェントを 1 回だけ立てること。

## 受け口

移るとは、機械が手元の checkout を対象のブランチへ `git switch` で替えること（手元に無ければ origin からその 1 本を取って作る）。移るのは、番号・URL・ブランチ名で呼ばれたときだけ。移った後のファイルは移った先のブランチの中身なので、移る前に読んだファイルを直すなら読み直す。

- 番号・URL・ブランチ名 → `catchup.py --switch <それ> --out`。番号はいま居るリポジトリの物で、別のリポジトリは URL か、`catchup.py` の旗 `-R owner/repo` で指す。
- 引数なし・`this`・焦点の語だけ → `catchup.py this --out`
- commit・範囲 `A..B` → `catchup.py <それ> --out`
- 会話の話題 → 会話の中で番号・ブランチ・commit に結び付けば、その対象を `--switch` 無しで呼ぶ。結び付かなければ、会話の往復を材料にし（取り方は [references/targets.md](references/targets.md) の「会話の話題」）、`catchup.py` は手順 9 の `--render` だけを呼ぶ。
- `setup` → [references/setup.md](references/setup.md)（準備のコマンドと、機械がすること）を読んで従う。

焦点の語と旗は対象の後ろにそのまま置き、`--out` を末尾にする（`catchup.py --switch 1569 指摘 --out`）。

## 手順

1. 対象を決める。対象が会話の話題・数字だけの語・commit のとき、引数なしで今のブランチに PR も番号も無いとき、焦点の語や `--full` などの旗を付けるとき、機械が移らなかったときは、先に [references/targets.md](references/targets.md)（対象の読み方・会話からの推定・聞き返す形・移る条件・旗）を読む。
2. 受け口のとおりに機械を呼ぶ。`--out` は必ず引数の末尾に付ける。出力は 1 件で 9〜16 万バイトあり、Bash の 1 回の上限（約 3 万バイト）を越える。付けないと出力がファイルへ退避され、読み直しに `gh` ごと 2 回走る。
3. 返ってきた材料のファイルを Read で読む（`cat` も退避されるので使わない）。`セクション（Read の offset）:` の行がセクションごとの開始行を示す。Read が途中で切れたら offset を進める（続きを読むだけで、機械は呼び直さない）。
   - `変更の地図` より前のセクションは全部読む。
   - `変更の地図` は頭（規模・変更ファイル・名前の言及・新規ファイルの先頭と骨組み）だけを読む。既存ファイルの変更の抜粋は、説明の背景に要るときだけ読む（差分は機械がページに全部載せる）。
   - 手順 2 の標準出力の `描く材料は <path> に書いた` の path は、読まずに手順 8 へ渡す。この行の代わりに「描く材料を組めなかった（訳）。ページは描けない」と出ていたら、手順 7〜9 を飛ばす。
4. 「本文（材料）」を読む。切れていれば `gh pr view <番号> --json body -q .body`（issue は `gh issue view`、commit は `git show`）で全文を取る。本文が飛ばす前提（製品が何か・部品の役割・前の番号の中身）は、README の冒頭・触るファイルの先頭のコメント・材料に出た前の番号の冒頭で、要る分だけ埋める。
5. 書く前に確かめる。機械の語をそのまま写すと、済んだ件が「未対応」に読めるなど、答えが逆になる。
   - `CI: 赤` → 「CI が落ちた理由（材料）」を読む。焦点でそのセクションを外していれば `catchup.py <番号> CI --out` で呼び直す。読めないチェックは URL を開く。
   - `（名指しは無い。私の件への発言）` → 私への依頼か、私の push で既に済んでいないかを、本文と差分で見る。
   - 止めている原因が別の番号 → `gh pr view <番号> --json author,reviewRequests,reviewDecision,updatedAt` を 1 回打ち、その番号が誰のターンかを見る。
   - 取り込みが「GitHub が判定中（UNKNOWN）」で、件が open → 機械は呼び直さず、`gh pr view <番号> --json mergeable -q .mergeable` を 1 回打つ。まだ判定中なら「衝突の有無は GitHub が判定中（未確認）」と書く。
   - 会話に GitHub に無い依頼（口頭・チャットのレビュー依頼など）が出ている → この件での私の立場は会話の側を正とし、私が動かせる件として書く。GitHub に依頼が無いことを 1 文添える。
   - 機械が材料を切って続きの口（`--full`・`--limit`・`--frame`・`gh … view`）を書いている → その口で取る。取った分は「見ていないもの」に書かない。
6. [references/fields.md](references/fields.md)（JSON の形・ページの上のフィールドの書き方・PR でないときの形・言葉）を Read で開く。キー名と形はこの本文に無いので、どの件でも毎回開く。
7. 「この PR がすること」を書くときは、[references/explain.md](references/explain.md)（ひとこと・説明・変更点・図の書き方）も開く。書くのは、対象が PR、または本文か差分の有る issue・ブランチ・commit で、焦点が無いか `地図` を含むとき。
8. フィールドの JSON を Write で書く。置き場は、描く材料の path の `.json` を `-fields.json` に替えた path（描く材料が無ければ OS の一時ディレクトリ）。
9. `catchup.py --render <描く材料の path> <フィールドの JSON の path>` で描く。何にも結び付かない会話の話題は、描く材料の path の代わりに `-` を渡す。機械が直す所を 1 件 1 行で言って終了コード 2 で止まったら、直して呼び直す（字数と個数の上限は機械が見る）。
10. 機械が標準出力に出した 2 行（ページの path と 1 行の要約）をそのまま返す。前置き・説明・指摘・差分を足さない。全文を求められたときだけ、材料のファイルを 1 文字も変えずにコードブロックで貼る。手順 3 で描く材料を組めなかったと分かったときだけは、手順 6 の fields.md の書き方で、いまのターンの 1 文（`headline`）・前回からの動き（`where`）・止めているもの（`turn`）・次にやること（`next`）を材料から書いて端末に返し、描けなかったことと機械の言い分を 1 文添える。