reflect

ふりかえり

セッション終了時のふりかえりです。現在の会話を読み直し、見落とされたことや失われることを明らかにして、セッションが終わる前にユーザーが選んだ対応を実行します。

対象範囲と基本姿勢

• 会話の範囲内で行います。 コンテキストに含まれる会話をふりかえります。トランスクリプトファイルや git の履歴は解析しないでください。これは gstack-retro（コミット履歴のふりかえり）でも gstack-learn（学びの記録）でもありません。今後の対応に集中してください。
• この後、セッションは終了すると考えてください。 ここで確立した情報がファイル、Issue、PR に書かれなければ、すべて失われます。そのため、このスキルの主な役割は、注釈的なものではなく、行き場のない知識を残すことです。苦労して見つけた落とし穴が CLAUDE.md に記録されなければ、次のセッションでも同じデバッグを繰り返すことになります。
• コンパクションについて正直に伝えてください。 セッションがコンパクションされていた場合、何が保持されたかをふりかえり、そのことを明確に伝えてください。要約されたターンを思い出したかのように捏造してはいけません。
• デフォルトでは成果物を作成しません。 見つかった内容は会話内にとどめます。提示した項目は使い捨てです。ユーザーが対応するか、無視します。ファイルへの書き込みは、ユーザーが書き込みを伴う対応を選んだ場合、または明示的に依頼した場合に限ります。
• 報告は控えめにし、むやみに列挙しないでください。 誤った「未完了事項」や一度きりの作業へのスキルの提案は、何も言わないよりも悪影響があります。以下の確信度基準を適用してください。迷ったら、報告しないでください。
• 提案の前に確認してください。 文書化されていない、または追跡されていないと主張する前に、必ず確認してください。実際の現行内容に対する実際の修正となるよう、提案内容を提示する前に対象ファイル（CLAUDE.md、AGENTS.md、README.md）を読み、未解決の Issue を検索してください。すでに記載されている内容を重複して提案してはいけません。

ステップ 1 — ふりかえる

会話全体を最初から最後まで読み直してください。何かを指摘する前に、会話の流れ全体を把握してください。

ステップ 2 — 検出器を実行する

各検出器には厳格な確信度基準があります。基準を満たさない項目は、何も言わずに除外してください。

A. 未完了事項 — ユーザーが対応しなかったアクション項目や決定事項。

• 主な判断基準：アシスタントのメッセージで、2 つ以上の決定事項や質問をひとまとめにして提示した箇所を見つけ、ユーザーの次の返信ですべてに答えているか確認します。たとえば、3 つ質問してユーザーが 1 つだけ答えた場合、答えられていない項目が最も価値の高い候補です。ユーザーが長文の冒頭だけに反応し、残りは読み飛ばした可能性があります。
• そのほか、「X は後でやりましょう」という明示的な発言、未対応のままになった TODO、認識されたものの修正されなかったエラーも拾います。
• 基準：会話内に、その項目が提起され、未解決のままであることを示す具体的な証拠があること。

B. ドキュメントの不整合 — このセッションでの変更により古くなったドキュメント。

• 対象を限定します。「README のセクション X は、Y を変更したため、現在の内容と一致しません」のように、ファイル名と具体的な不整合を示してください。
• 基準：このセッションで行った変更が、既存ドキュメントに記載された動作と直接矛盾していること。ドキュメント全体の見直しを一から提案してはいけません。

C. スキル化／ハーネスの不足 — 新しいスキルやエージェントで引き受けられる反復作業、または再利用可能なスキルとして記録する価値のある複数ステップの手順。

• 基準：このセッション中に同じパターンが少なくとも 2 回繰り返されたか、明らかに繰り返し発生する作業であること。単発の作業は対象になりません。 D. CLAUDE.md / AGENTS.md の不足 — メモリファイルの改善です。各指摘を次の2つの軸で分類します。
• スコープ： project（リポジトリ内の CLAUDE.md／AGENTS.md）か global（ユーザーの ~/.claude/CLAUDE.md）です。好みがリポジトリ固有か、どこでも当てはまるかに応じて選びます。
• 種類：
  • append → ユーザーが明確に持っているものの、まだ書き留めていない新しい原則、好み、規約です。
  • rewrite → このセッションで誤り、古い、または誤解を招くと判明した既存の文です。現在の行を引用し、置き換える文面を提案します。単に既存の記述に付け加えるだけにしないでください。
  • hook → 文章ではなく、settings.json のフックです。「今後は、X のたびに Y を行う」という形式のものは自動化された動作であり、ハーネスが実行する必要があります。メモリファイルの文章にはできません。対応するときは update-config スキルを通じて設定します。
• 基準： ユーザーがその好みを持っていることを示す明確な証拠があること。ユーザーが明言した、あなたの対応を訂正した、または同じことが繰り返し起きた場合です。一度だけの文体上の選択は該当しません。

E. 行き場のない知識 — このセッションで確立された、現在この会話にしか存在しない長期的に有用な事実です。

• 該当するもの：苦労して見つけた落とし穴（X を先に実行しないとビルドが失敗するなど）、環境やツールの制約、ドキュメントの説明と異なる外部 API の実際の仕様、試して却下したアプローチとその理由、決定とその根拠、コードの特定の部分がそのような形になっている自明でない理由です。
• 却下したアプローチも、採用したアプローチと同じくらい価値があります。「X を試したが、Y の理由で失敗した」という情報を残さないと、次のセッションでも同じことが繰り返されます。
• 基準： 以下の3つすべてを満たすこと。（1） 知るのに実際の手間がかかった（失敗、デバッグの繰り返し、ドキュメントの調査など）、またはユーザーが事実として述べた。（2） 誰かが再び直面する可能性がある。（3） すでに書き留められていないことを確認した。30秒で調べられることは基準を満たしません。
• 次に、以下の表を使って保存先を決めます。妥当な保存先がない指摘は、指摘に該当しません。

F. 未リリースの作業 — このセッションでしか存在せず、永続的に残す場所が必要な作業です。

• PR が必要： 作業ツリーまたは未プッシュのブランチに、レビューできる状態の実際のコード変更があること。変更が存在し、まとまっていることが基準です。開くのが恥ずかしいような未完成の編集は該当しません。
• issue が必要： セッションで見つかったものの、実施しない具体的なフォローアップです。別の人が初めて見ても対応できる程度に具体的（何を、なぜ、どこで行うかのおおよその説明）であり、すでに追跡されていないことが基準です。オープン中の issue を確認してから提案してください。「いつかエラー処理を改善する必要がある」では不十分です。「parseConfig は YAML エラーを握りつぶして {} を返すため、エラーを表面化させる必要がある。config.ts:41 を参照」のような内容なら該当します。
• 自分の判断で issue や PR を作成してはいけません。ほかのすべてと同様、ステップ4を通じて対応します。

知識の保存先

D／E に該当するすべての指摘を、いずれか1つの保存先に割り当てます。よくある失敗は保存先を誤ることです。リポジトリ固有のビルド上の注意点をグローバルメモリファイルに書くと、ほかのすべてのプロジェクトに影響してしまいます。

知識の内容	保存先
すべてのリポジトリで当てはまる好みや習慣（口調、ツール、ワークフロー）	グローバルな ~/.claude/CLAUDE.md
このリポジトリでエージェントが必要とする規約や制約	プロジェクトの CLAUDE.md ／ AGENTS.md
インストール手順、機能の説明、コントリビューター向けの注意点など、人間のコントリビューターやユーザーに必要な情報	README.md または該当するドキュメント
特定の場所に関連する、コードがこの形になっている理由	該当箇所のコードコメント
今は実施しないものの、実施する価値がある作業	GitHub issue
存在するものの、ほかの人には見えない変更	コミットと PR
繰り返し行う複数ステップの手順	新しいスキル（検出器 C）
「今後は、X のたびに Y を行う」	update-config を通じて設定する settings.json のフック

事実の保存先が2つ必要に思える場合は、実際に必要とする対象者に合うほうを選んで次に進みます。同じ文を3つのファイルに重複して書かないでください。

Step 3 — 1つのフラットなランキングリストにまとめる

基準を満たしたすべての検出器の指摘事項を集め、メモリ上の1つのフラットなリストにまとめます。各指摘事項のカテゴリタグ（A–F）は保持しますが、カテゴリ別にリストをグループ化してはいけません。

• 価値 = 信頼度 × 影響度 × 持続性の損失でランキングします。この3つ目の要素が同点時の決め手です。どちらも同程度に有用な指摘事項なら、このセッションが終了すると取り戻せないほうを優先します。この記録以外のどこにも存在しない落とし穴は、後から誰でもコードを見れば気づけるドキュメントの修正より優先されます。
• ランキングの前に統合します。同じ保存先ファイルに追加する2つの指摘事項は、1つの指摘事項、1つの質問、1つの編集にまとめます。
• 上位5件を選びます。残りは破棄します。基準を満たした指摘事項が5件を超える場合は、ユーザーに残りがあることがわかるように、1行で伝えます（例：「信頼度の低い項目を3件除外しました」）。ただし、残りの指摘事項は提示しません。
• どの基準も満たさなかった場合は、「特に指摘することはありません」と伝えて終了します。

Step 4 — 指摘事項を1件ずつ質問する

候補リストを、ランキング順に個別の単一選択式AskUserQuestion質問として、指摘事項ごとに1つの質問で提示します。最も強く推奨する指摘事項を最初にしてください。複数の指摘事項を1つのmultiSelect質問にまとめてはいけません。グループ化すると、選びにくくなります。指摘事項ごとに個別の判断を仰ぎます。

各指摘事項の質問では、次のようにします。

• header：カテゴリ名。「未完了項目」、「ドキュメントの不足」、「スキル化」、「CLAUDE.md」、「ナレッジ」、または「公開」
• question：指摘事項の内容（何が抜けているか／何が古いか／何が失われるか／何を開くか）を具体的に述べ、保存先を明記してから、どうするかを尋ねます。
• options（単一選択、multiSelect: false）：推奨する対応を最初に置き、(Recommended)とラベルを付けます。その後に現実的な代替案を並べ、最後は明確な辞退の選択肢にします。カテゴリごとの推奨対応の例：
  • A（未完了項目）：「今すぐ完了する」または、規模が大きい場合は「次の最小ステップを実行する」
  • B（ドキュメントの不足）：「差分を表示して適用する」
  • C（スキル化）：「SKILL.mdの骨組みを作成する」
  • **D（CLAUDE.md/AGENTS.md）：**追記／書き換えの場合は「編集内容を表示して適用する」。フックの場合は「update-config経由でフックを設定する」
  • E（ナレッジ）：「今すぐ<保存先>に書き込む」。保存先の選択に明確な理由がある場合は、同じ対応を曖昧に言い換えるのではなく、他の保存先を代替案として提示します。
  • F（公開）：「PRを作成する」／「Issueを作成する」。作成前にドラフトのタイトルと本文を表示します。
  • 常に「スキップ」／「そのままにする」を最後に含めます。

質問は1件ずつ（または1回の呼び出しでいくつかずつ）行いますが、1つの質問に複数の指摘事項を含めてはいけません。これにより、回答ごとに対応してから次に進めます。

Step 5 — 選択された項目に対応する

ユーザーが対応を選んだ各指摘事項について、このセッション内ですぐに実行します。

• **A（未完了項目）：**抜けている項目を完了するか、規模が大きい場合は次の最小ステップを確認します。
• **B（ドキュメントの不足）：**正確な差分を作成し、承認後に適用します。
• C（スキル化）：SKILL.mdの骨組みを作成するか、/gstack-skillifyを提案します。/reflect内でスキル全体の構築を無理に進める必要はありません。簡易版を用意するか、後回しにするだけでもかまいません。
• **D（CLAUDE.md/AGENTS.md）：**追記／書き換えの場合は、メモリファイルの正確な差分を提示します（書き換えの場合は変更前の行を引用します）。承認後に適用します。フックの場合は、update-configを呼び出して設定します。
• **E（ナレッジ）：**現在のファイルとの差分として、振り分け先に実際に書き込みます。ファイル既存の文体、セクション構成、詳細度に合わせます。事実とその影響だけに絞ります。セッションの経緯を段落で説明するより、長く残る1行のほうが適切です。会話の記録をメモリファイルに貼り付けてはいけません。
• **F（公開）：**PRの場合は、可能であれば/gh-prに引き継ぎます。利用できない場合は、コミット、プッシュして、ドラフトのタイトルと本文でPRを作成します。Issueの場合は、ドラフトのタイトルと本文で作成し、リポジトリ内で読者が確認する場所からリンクします。まずドラフトを提示し、ユーザーの承認を得てから作成します。

ユーザーが書き込みを伴う対応を選択するか、書面での記録を明示的に求めない限り、何もディスクに保存しません。