Catch Up

目的

ユーザーの最後の発言以降に何が変わったかを、ユーザーが腹落ちする形で伝える。 ユーザーにしかできない判断は、返信を読むだけで判断できるように示す。

ユーザーは自分の最後の発言を覚えているが、その後のことは知らない前提で書く。 通知や subagent の結果は、ユーザーの発言に含めない。 手動で呼ばれたときや、状況の説明を求められたときは、その依頼の 1 つ前のユーザーの発言を起点にする。

使うタイミング

• 実装中に、合意した内容を変える必要のある問題を見つけたとき
• ユーザーに状況の説明を求められたとき

合意した内容とは、ユーザーが依頼や会話で明示したか、提案を承認した事項を指す。 対象は、仕様・変更範囲・名前・型・signature・モジュールの分け方・前提とする。

合意した範囲の中で直せる問題では使わない。 コードや仕様についての調査や質問への回答では使わない。

作業を止める

合意を変える必要のある問題を見つけたら、その問題に関わる作業を止めてから伝える。 ユーザーが決めるまで、判断待ちの事項に関わる作業を進めない。 判断を先取りして実装すると、ユーザーが判断する前に結果が決まってしまうため。

判断待ちを伝えたら、そのターンを終える。 同じターンで他の作業を続けると、判断待ちが後の報告に埋もれるため。 判断待ちに関わらない作業は、指示があれば進める作業として報告に書く。

集める

伝える前に、次を集める。

• ユーザーの最後の発言以降に、自分が加えた変更と下した判断
• subagent の結果と、他の参加者からのメッセージ
• 作業で触れた PR、CI、ブランチの現在の状態
• ユーザーの判断を待っている事項。最後の発言より前から残っているものも含める

集める間は、状態を変えない。 コードの変更、アプリケーションの起動、外部への投稿をしない。 書く数値と状態は、元になった事実と照らし合わせる。食い違いを直したら、そのことも書く。 動作の確認も求められた場合は、確認を済ませてから集め、その結果も含めて伝える。

判断待ちの事項は、ユーザーにしかできない判断や操作に限る。 例えば、仕様の選択、承認、不可逆な操作、自分にない権限を要する操作が該当する。 自分で続けられる作業は、判断待ちに含めない。 判断待ちがないのに、判断を作って並べない。

書く順序

1. 判断待ちがあるかどうかを、最初の 1 文で書く
2. 依頼ごとに、何が起きたかを 1 行ずつ書く
3. 見つかった問題を説明する
4. 判断待ちの事項を並べる
5. 判断を待たずに進められる作業を、指示があれば進める作業として 1 行で書く

判断待ちと変化のどちらもなければ、そう書いて終える。 他に必要な報告項目があれば、別の報告に分けず、この報告の中に含める。

2. 起きたこと

依頼ごとに、結果と状態を 1 行で書く。 状態は、完了、実行中、失敗、未確認、判断待ちのどれかで書く。 ユーザーの判断を待っているものは、判断待ちと書く。

経緯は短くする。言葉は判断のために使う。 ユーザーにとって何も変わらなかった作業は書かない。

3. 見つかった問題

問題ごとに、次の順で説明する。

1. 何が起きるか。具体的な入力や操作と、その結果で示す
2. なぜ起きるか。どの処理が、どの値を、どう扱うから起きるのかを書く
3. 依頼や合意した内容のどこに影響するか

ユーザーが自分の言葉で言い直せるまで、具体的に書く。 何が起きるかを言わない比喩で、説明した気にならない。

悪い例: 設定が古いと、同期が静かに壊れる
良い例: 設定ファイルに `version` がないと、同期処理はエラーを出さずに空の一覧を保存する

4. 判断待ちの事項

判断ごとに、次の形で書く。

判断: 古い形式の設定ファイルをどう扱うか
- A: 読み込み時に新しい形式へ変換する → 利用者は何もしなくてよいが、変換処理を保守し続ける
- B: エラーにして、移行手順を案内する → 変換処理は不要だが、利用者が手で設定を直す
推奨: A。利用者の手間を減らすことを優先する。古い形式の利用者が多く、手で直す負担が大きいため
B にしない理由: 変換処理を持たずに済む利点より、移行手順を読まずに更新した利用者が同期できなくなる影響のほうが大きいため

• 選択肢ごとに、選んだ結果として何が変わるかを 1 文で書く
• 推奨には、何を優先してそれを選んだかと、根拠になった事実を書く
• 推奨しない選択肢ごとに、その選択肢の利点を手放してよい理由を書く
• 不可逆な操作や、先に済ませるべき操作があれば書く
• 判断に必要なのに分からない事実は、「不明」と書く
• 待つことで期限切れやデータの損失が起きる場合だけ、待つ影響を書く

複数の事項が同じ判断を待っているなら、判断と推奨を 1 回だけ書き、事項ごとに 1 行ずつ添える。 返信の長さを抑えるために、事項を減らしたり、件数やリンクだけで済ませたりしない。

推奨の理由だけでは、他の選択肢を選ばずに何を手放したのかが分からない。 選ばない理由まで示し、ユーザーが自分の判断として説明できるようにする。

文の書き方

• 1 文に 1 つのことを書く
• 何が起きるかを言わない比喩や抽象的な言葉を使わず、起きることをそのまま書く
• 1 つの概念には 1 つの名前を使い、途中で言い換えない
• 自分が付けた呼び名ではなく、ユーザーが知っている名前で呼ぶ
• commit のハッシュ、ファイルパス、コマンド、件数は、ユーザーが判断や操作に使うときだけ書く
• 専門用語や内部の事情を前提にしない
• 前置きや、これから話す内容の予告を書かない

3 つ以上の要素のつながりは、文より図のほうが早く伝わる場合だけ、短い図で示す。 状態の一覧や判断待ちの一覧は、図にしない。 同じ事実を、文と図で重ねて書かない。