ce:compound-refresh

Compound Refresh

docs/solutions/ の品質を長期にわたって維持します。このワークフローでは、既存の学びを現在のコードベースと照らし合わせて確認し、それらに依存する派生パターンドキュメントを更新します。

モードの判定

$ARGUMENTS に mode:autofix が含まれているか確認します。含まれている場合は、引数からそれを取り除き（残りをスコープのヒントとして使用）、自動修正モードで実行します。

モード	条件	動作
対話型（デフォルト）	ユーザーがその場にいて、質問に回答できる	判断が曖昧なケースでは決定を尋ね、実行するアクションを確認します
自動修正	引数に mode:autofix が含まれている	ユーザーとのやり取りは行いません。曖昧さのないアクション（維持、更新、統合、自動削除、十分な根拠に基づく置換）をすべて実行します。曖昧なケースは古い情報としてマークします。最後にサマリーレポートを作成します。

自動修正モードのルール

• ユーザーへの質問はすべて省略します。 入力を求めて処理を止めないでください。
• スコープ内のすべてのドキュメントを処理します。 スコープを絞る質問はしません。スコープのヒントがない場合は、すべてを処理します。
• 安全なアクションをすべて試みます。 維持（変更なし）、更新（参照を修正）、統合（統合先のドキュメントに吸収されたドキュメントを削除）、自動削除（曖昧さのない基準を満たす場合）、置換（根拠が十分な場合）を実行します。書き込みに成功した場合は、レポートに適用済みとして記録します。書き込みに失敗した場合（権限拒否など）は、レポートに推奨として記録し、処理を続けます。停止したり、権限を求めたりしないでください。
• 判断に迷う場合は、古い情報としてマークします。 分類（更新、置換、統合、削除）が本当に曖昧な場合、または置換の根拠が不十分な場合は、フロントマターに status: stale、stale_reason、stale_date を設定して、古い情報としてマークします。古い情報としてマークする書き込みにも失敗した場合は、推奨事項として記載します。
• 慎重に判断します。 対話型モードでは、判断が微妙なケースについてユーザーに質問します。自動修正モードでは、判断が微妙なケースを古い情報としてマークします。誤ったアクションを取るより、古い情報としてマークすることを優先します。
• 必ずレポートを作成します。 レポートが主な成果物です。適用済み（書き込みに成功したアクション）と推奨（書き込みできなかったアクション。人が実行するか、スキルを対話型で実行する際に必要な根拠をすべて記載）の2つのセクションで構成します。権限の有無にかかわらず、レポートの構成は同じです。各アクションがどちらのセクションに記載されるかのみが異なります。

対話の原則

これらの原則は対話型モードにのみ適用されます。自動修正モードでは、ユーザーへの質問をすべて省略し、上記の自動修正モードのルールを適用します。

ce:brainstorm と同じ対話スタイルに従います。

• 質問は一度に1つずつ行います。利用可能な場合は、プラットフォームの応答待ちを行う質問ツール（Claude Code の AskUserQuestion、Codex の request_user_input、Gemini の ask_user）を使用してください。それ以外の場合は、番号付きの選択肢をプレーンテキストで提示し、続行する前にユーザーの回答を待ちます。
• 自然な選択肢がある場合は、選択式を優先します。
• まずスコープと意図を確認し、必要な場合にのみ絞り込みます。
• 根拠を確認する前に、ユーザーに判断を求めてはいけません。
• 推奨案を先に示し、簡潔に説明します。

目的は、チェックリストをユーザーに無理にこなさせることではありません。できるだけ手間をかけずに、適切なメンテナンスの判断を支援することです。

更新の順序

次の順序で更新します。

1. まず、関連する個別の学びのドキュメントを確認します
2. どの学びが有効なままだったか、更新、統合、置換、削除されたかを記録します
3. その後、それらの学びに依存するパターンドキュメントを確認します

理由：

• 学びのドキュメントが主な根拠となるため
• パターンドキュメントは、1つ以上の学びから派生するため
• 古くなった学びによって、パターンが実際以上に有効に見えることがあるため

ユーザーがパターンドキュメントを最初に指定した場合は、懸念を把握するためにそこから確認を始めてもかまいません。ただし、パターンを変更する前に、根拠となる学びのドキュメントを調べてください。

保守モデル

候補となる各成果物を、次の5つの結果のいずれかに分類します。

結果	意味	デフォルトのアクション
Keep	現在も正確で、有用である	デフォルトではファイルを編集せず、レビュー済みで、引き続き信頼できることを報告します
Update	中核となる解決策は引き続き正しいものの、参照先にずれが生じている	根拠に基づいて、その場で編集を適用します
Consolidate	2つ以上のドキュメントの内容が大きく重複しているが、いずれも正しい	固有の内容を正規のドキュメントに統合し、包含されたドキュメントを削除します
Replace	古い成果物は誤解を招くようになっているが、より適切な置き換え先が分かっている	信頼できる後継を作成してから、古い成果物を削除します
Delete	もはや有用でも適用可能でもなく、独自性もない	ファイルを削除します。必要な場合は、後から誰でも Git の履歴から復元できます

基本ルール

1. 証拠に基づいて判断します。 以下のシグナルは判断材料であり、機械的な採点表ではありません。成果物が今も信頼できるかどうかは、エンジニアリング上の判断に基づいて決めてください。
2. 書き込みを伴わない Keep を優先します。 レビューの記録を残すだけの目的で、ドキュメントを更新しないでください。
3. 現実に合わせてドキュメントを更新し、その逆は行いません。 現在のコードが学習内容と異なる場合は、現在のコードを反映するよう学習内容を更新してください。このスキルの役割はドキュメントの正確性を保つことであり、コードレビューではありません。コードの変更が「意図的なもの」か「デグレード」かをユーザーに尋ねないでください。コードが変更されたなら、ドキュメントもそれに合わせてください。コードが誤っているとユーザーが考える場合、それはこのワークフローの範囲外にある別の懸念事項です。
4. 迷わず判断し、質問を最小限に抑えます。 ファイル名の変更、クラスの移動、参照切れなど、証拠が明確な場合は更新を適用してください。インタラクティブモードでユーザーに尋ねるのは、適切な対応が本当に曖昧な場合に限ります。自動修正モードでは、曖昧なケースは質問せず、古いものとしてマークしてください。目指すのは、すべての指摘について質問することではなく、判断が必要な場合に人間の監督を受けながら保守を自動化することです。
5. 価値の低い変更を避けます。 誤字の修正、表現の推敲、正確性や使いやすさを実質的に改善しない見た目だけの変更を目的として、ドキュメントを編集しないでください。
6. 意味のある、証拠に裏付けられた乖離がある場合にのみ Update を使用します。 パス、モジュール名、関連リンク、カテゴリーメタデータ、コードスニペット、明らかに古くなった記述などは、修正によって正確性が実質的に向上する場合に修正できます。
7. 実際に後継となるものがある場合にのみ Replace を使用します。 次のいずれかに該当する場合です。
   • 現在の会話に、最近解決され、検証済みの置き換え修正が含まれている。
   • ユーザーから、後継となるものを正確に記述するのに十分な具体的情報が提供されている。
   • コードベースの調査で現在のアプローチが見つかり、後継として記述できる。
   • 新しいドキュメント、パターンドキュメント、PR、課題に、後継を示す強い証拠がある。
8. コードがなくなったら Delete します。 参照先のコード、コントローラー、ワークフローがコードベースに存在せず、後継も見つからない場合は、そのファイルを削除してください。一般的なアドバイスが「妥当」だからといって、安易に Keep を選ばないでください。削除された機能についての学習内容は、その機能が今も存在すると読者に誤解させます。Keep と Delete のどちらにするか迷う場合は、インタラクティブモードではユーザーに尋ね、自動修正モードでは古いものとしてマークしてください。ただし、参照先のファイルがなく、対応するコードも見つからない場合は、迷うケースではありません。Delete を示す強力で明白な証拠です。自動的に削除してください。
9. 正確性だけでなく、ドキュメント群の構成も評価します。 各ドキュメントが正確かどうかに加えて、そのドキュメントが今も適切な知識単位かどうかも評価してください。2つ以上のドキュメントで内容が大きく重複している場合は、別々のままにするか、対象範囲をより明確に分けるか、正本となる1つのドキュメントに統合するかを判断してください。重複したドキュメントは、気づかないうちに乖離するため危険です。同じ内容を述べている2つのドキュメントも、いずれは異なる内容になってしまいます。
10. アーカイブするのではなく、削除します。 _archived/ ディレクトリはありません。ドキュメントが不要になった場合は削除してください。Git の履歴が、削除したすべてのファイルを保存するアーカイブです。専用のアーカイブディレクトリを作ると、古いドキュメントが蓄積し、検索結果を汚染し、誰にも読まれなくなります。削除したドキュメントが必要になった場合は、git log --diff-filter=D -- docs/solutions/ で見つけられます。

対象範囲の選択

まず、docs/solutions/ 内の学びとパターンのドキュメントを探します。

除外対象：

• README.md
• docs/solutions/_archived/（レガシーです。このディレクトリが存在する場合は、レポートで整理対象として指摘してください）

docs/solutions/ 内のすべての .md ファイルを探します。ただし、README.md と _archived/ 以下のファイルは除外します。_archived/ ディレクトリが存在する場合は、復元または削除が必要なレガシー成果物としてレポートに記載してください。

$ARGUMENTS が指定されている場合は、先にそれを使って対象範囲を絞り込んでから進めます。次の照合方法を順番に試し、最初に結果が得られた方法で停止します。

1. ディレクトリ名で照合 — 引数が docs/solutions/ 内のサブディレクトリ名と一致するか確認します（例：performance-issues、database-issues）
2. フロントマターで照合 — 学びのフロントマターにある module、component、または tags フィールドを検索します
3. ファイル名で照合 — ファイル名と照合します（部分一致でもかまいません）
4. コンテンツを検索 — 引数をキーワードとしてファイルの内容を検索します（機能名や機能領域に便利です）

一致するものが見つからない場合は、その旨を報告してユーザーに確認を求めます。自動修正モードでは、見つからなかったことを報告して停止します。対象範囲を推測してはいけません。

候補となるドキュメントがない場合は、次のように報告します。

No candidate docs found in docs/solutions/.
Run `ce:compound` after solving problems to start building your knowledge base.

フェーズ 0：評価と振り分け

ユーザーに分類を求める前に、次の手順を実行します。

1. 候補となる成果物を探します
2. 対象範囲を見積もります
3. 適切な範囲に合った、最も負担の少ない進め方を選びます

対象範囲による振り分け

対象範囲	使用する場面	対話形式
限定的	有力なファイルが 1～2 件ある場合、またはユーザーが特定のドキュメントを指定した場合	直接調査してから、推奨事項を提示します
一括	おおむね 8 件以下の、互いに独立したドキュメントが中心の場合	先に調査してから、分類した推奨事項を提示します
広範	ドキュメントが 9 件以上ある場合、対象が曖昧な場合、またはリポジトリ全体の古いドキュメントを調査する場合	先にトリアージを行い、その後、複数のまとまりに分けて調査します

広範な対象範囲のトリアージ

対象範囲が広い場合（候補となるドキュメントが 9 件以上）は、詳細な調査に入る前に、簡易的なトリアージを行います。

1. 一覧化 — すべての候補ドキュメントのフロントマターを読み、モジュール／コンポーネント／カテゴリ別にまとめます
2. 影響度によるクラスタリング — 学びとパターンのドキュメントが最も密集している領域を特定します。同じモジュールを対象とする学びのドキュメント 5 件とパターンのドキュメント 2 件からなるクラスタは、単独のドキュメントしかない領域が 5 つある場合より影響度が高くなります。1 つのドキュメントの古さが他のドキュメントにも影響する可能性が高いためです。
3. 変更の有無をスポットチェック — 各クラスタについて、主に参照されているファイルが現在も存在するか確認します。影響度の高いクラスタで参照先が見つからないことは、調査の開始場所を決める最も強い兆候です。
4. 開始領域を提案 — 影響度が最も高いクラスタと簡潔な理由を提示し、ユーザーに確認または変更を求めます。自動修正モードでは質問を省略し、影響度の高い順にすべてのクラスタを処理します。

例：

Found 24 learnings across 5 areas.

The auth module has 5 learnings and 2 pattern docs that cross-reference
each other — and 3 of those reference files that no longer exist.
I'd start there.

1. Start with auth (recommended)
2. Pick a different area
3. Review everything

まだアクション選択の質問はしないでください。まず根拠を集めてください。

フェーズ 1：候補となる学びを調査する

対象範囲内の各学びについて、その内容を読み、主張を現在のコードベースと照合し、推奨事項をまとめます。

学びには、それぞれ独立して古くなる可能性のある複数の側面があります。表面的な確認で明らかな変化は見つかりますが、古さはより深い部分に潜んでいることがよくあります。

• 参照先 — 記載されているファイルパス、クラス名、モジュールは今も存在していますか。それとも移動していますか？
• 推奨される解決策 — その修正方法は、現在のコードの実際の動作に合っていますか？ファイル名が変わり、実装パターンもまったく異なる場合は、単なるパスの更新では済みません。
• コード例 — 学びにコードスニペットが含まれている場合、それらは現在の実装を反映していますか？
• 関連ドキュメント — 相互参照されている学びやパターンは、今も存在し、一貫していますか？
• 自動メモリ（Claude Code のみ）— システムプロンプトに挿入された自動メモリブロックに、同じ問題領域の項目がありますか？そのブロックを直接確認します。ブロックがない場合は、この観点をスキップします。学びの推奨とは異なるアプローチを説明するメモリの記述は、追加の陳腐化シグナルになります。
• 重複 — 調査中に、対象範囲内の別のドキュメントが同じ問題領域を扱っている、同じファイルを参照している、または類似した解決策を推奨している場合は記録します。各重複について、次の項目を記録します。2 つのファイルパス、重複する側面（問題、解決策、根本原因、ファイル、予防策）、そして、より広範または最新と思われるドキュメント。これらのシグナルはフェーズ 1.75（ドキュメントセット分析）に反映されます。

調査の深さは、学びの具体性に合わせます。正確なファイルパスやコードスニペットを参照している学びは、一般原則を説明する学びよりも、詳細な検証が必要です。

陳腐化の分類：更新と置換

重要なのは、陳腐化が表面的（参照先は移動したが、解決策は同じ）なのか、本質的（解決策そのものが変わった）なのかを見極めることです。

• 更新の範囲 — ファイルパスの移動、クラス名の変更、リンク切れ、メタデータの陳腐化はあるものの、推奨される基本方針は今もコードの動作に合っています。ce:compound-refresh で直接修正できます。
• 置換の範囲 — 推奨される解決策が現在のコードと矛盾している、アーキテクチャ上のアプローチが変わった、またはそのパターンが推奨されなくなった場合です。つまり、新しい学びを書き起こす必要があります。置換を担当するサブエージェントは、すでに収集した調査の証拠を使い、ce:compound のドキュメント形式（フロントマター、問題、根本原因、解決策、予防策）に従って後継ドキュメントを作成します。オーケストレーターは学びをインラインで書き換えず、コンテキストを分離するため、サブエージェントに委任します。

境界： 解決策のセクションを書き換えたり、学びが推奨する内容を変更したりする必要があると気づいたら、そこで止めます。それは「更新」ではなく「置換」です。

メモリに由来する陳腐化シグナルは補助的なものであり、主な根拠ではありません。異なるアプローチを説明するメモリの記述だけでは、「置換」や「削除」を正当化できません。メモリのシグナルは、次の用途に使います。

• コードベースから得られた陳腐化の証拠を裏付ける（「置換」の根拠を強める）
• コードベースの証拠だけでは判断が微妙な場合に、さらに深く調査するきっかけにする
• 証拠レポートに背景情報を加える（「（自動メモリ [claude] の記述によると、この学びが書かれた後にアプローチ X が変わった可能性があります」）

自動修正モードでは、メモリのみから得られた陳腐化（コードベースによる裏付けがない場合）は、アクションではなく陳腐化マークの付与につなげます。

判断ガイドライン

間違いやすい3つのガイドライン:

1. 矛盾 = 強い Replace シグナル。 学習の推奨が現在のコードパターンや最近検証された修正と衝突する場合、それは軽微なドリフトではなく、その学習が積極的に誤解を招いています。Replace に分類します。
2. 古さだけではステイルのシグナルになりません。 2年前の学習でも現在のコードと一致していれば問題ありません。古さは、より注意深く調査するためのきっかけとしてのみ使用します。
3. 削除する前に後継を確認します。 Replace や Delete を推奨する前に、同じ問題領域を扱うより新しい学習、パターンドキュメント、PR、issue を探します。後継の証拠が存在する場合は、Delete よりも Replace を優先し、読者がより新しいガイダンスへ導かれるようにします。

フェーズ 1.5: パターンドキュメントの調査

基盤となる学習ドキュメントをレビューした後、docs/solutions/patterns/ 配下の関連するパターンドキュメントを調査します。

パターンドキュメントは影響力が大きいものです。ステイルなパターンは、ステイルな個別学習よりも危険です。将来の作業がそれを広く適用可能なガイダンスとして扱う可能性があるからです。依存する学習の更新された状態を踏まえて、一般化されたルールが依然として成立するかを評価します。

明確に裏付ける学習が存在しないパターンドキュメントはステイルのシグナルです。変更せずに残す前に注意深く調査します。

フェーズ 1.75: ドキュメントセット分析

個々のドキュメントを調査した後、一歩引いてドキュメントセット全体を評価します。目的は、現実との比較だけでなく、ドキュメント同士を比較したときに初めて見えてくる問題を捉えることです。

重複の検出

同じモジュール、コンポーネント、タグ、または問題領域を共有するドキュメントについて、次の観点で比較します:

• 問題の記述 — 同じ根底にある問題を記述していますか?
• 解決策の形 — 表現が異なっていても、同じアプローチを推奨していますか?
• 参照ファイル — 同じコードパスを指していますか?
• 防止ルール — 同じ防止の箇条書きを繰り返していますか?
• 根本原因 — 同じ根本原因を特定していますか?

3つ以上の観点で高い重複がある場合は、強い Consolidate シグナルです。問うべきは「将来のメンテナーが現在の真実を得るために両方のドキュメントを読む必要があるか、それとも一方がもう一方をほぼ繰り返しているだけか」です。

置き換えのシグナル

「古くて限定的な前身、新しくて正典となるドキュメント」というパターンを検出します:

• 新しいドキュメントが、古いドキュメントと同じファイル、同じワークフロー、そしてより広範なランタイム動作を扱っている
• 古いドキュメントが特定のインシデントを記述し、新しいドキュメントがそれをパターンへと一般化している
• 2つのドキュメントが同じ修正を推奨しているが、新しい方により良いコンテキスト、例、またはスコープがある

新しいドキュメントが古いドキュメントを明確に包含している場合、古いドキュメントは統合候補です。その固有の内容(もしあれば)は新しいドキュメントにマージし、古いドキュメントは削除します。

正典ドキュメントの特定

各トピッククラスター(問題領域を共有するドキュメント)について、どのドキュメントが正典となる信頼できる情報源であるかを特定します:

• 通常はクラスター内で最も新しく、最も広範で、最も正確なドキュメント
• メンテナーがこのトピックを検索したときに最初に見つけるべきもの
• 他のドキュメントが重複させるのではなく、参照すべきもの

クラスター内の他のすべてのドキュメントは、次のいずれかです:

• 独立 — 意味のある異なるサブ問題を扱っており、独立した参照価値がある。別々に保つ。
• 包含 — 固有の内容が正典ドキュメントのセクションとして収まる。統合する。
• 冗長 — 正典ドキュメントがすでに述べていることに何も追加しない。削除する。

検索価値テスト

2つのドキュメントを分けておくことを推奨する前に、次のテストを行います。「メンテナーが半年後にこのトピックを検索したとき、別々のドキュメントにすることで見つけやすくなるでしょうか。それとも、内容が食い違うリスクが生じるだけでしょうか。」

次の場合に限り、別々のドキュメントにする価値があります。

• それぞれが、個別に検索される可能性のある、実質的に異なるサブ問題を扱っている
• 対象となる読者または状況が異なる（例：一方はデバッグ、もう一方は予防について）
• 統合すると、2つの焦点を絞ったドキュメントよりも、扱いにくくナビゲーションしづらいドキュメントになる

いずれにも該当しない場合は、統合を優先してください。同じ内容を扱う2つのドキュメントは、いずれ内容が食い違い、互いに矛盾するようになります。これは、少し長めのドキュメントを1つ作るよりも望ましくありません。

ドキュメント間の矛盾チェック

対象範囲内のドキュメントに、明白な矛盾がないか確認します。

• ドキュメントAは「常にアプローチXを使う」と記載している一方で、ドキュメントBは「アプローチXを避ける」と記載している
• ドキュメントAは、ドキュメントBが非推奨としているファイルパスを参照している
• ドキュメントAとドキュメントBで、同じ問題と思われる事象について異なる根本原因を説明している

ドキュメント間の矛盾は、個々のドキュメントの古さよりも緊急性が高く、読者を積極的に混乱させます。統合（片方が正しく、もう片方が同じ内容の古い版である場合）または対象を絞った更新／置換によって、直ちに解決できるようフラグを付けてください。

サブエージェント戦略

複数の成果物を調査するときは、タスクが複雑そうだからという理由だけでなく、コンテキストを分離するためにサブエージェントを使います。状況に合った、最も軽量な方法を選んでください。

方法	使用する状況
メインスレッドのみ	対象範囲が狭く、ドキュメントが短い場合
順次実行するサブエージェント	1～2件の成果物に、読むべき関連ファイルが多数ある場合
並列実行するサブエージェント	相互の重複が少ない、真に独立した成果物が3件以上ある場合
バッチ処理するサブエージェント	広範な調査の場合。まず対象範囲を絞り、その後、複数のバッチに分けて調査する

サブエージェントを起動する際は、ユーザーが設定した権限設定が適用されるよう、mode パラメーターを省略してください。タスクのプロンプトには、次の指示を含めてください。

調査には、専用のファイル検索・読み取りツール（Glob、Grep、Read）を使ってください。ファイル操作にシェルコマンド（ls、find、cat、grep、test、bash）は使用しないでください。これにより、権限の確認を回避でき、より確実に調査できます。

また、システムプロンプトに挿入されている「ユーザーの自動メモリ」ブロックも確認してください（Claude Code のみ）。学習内容の問題領域に関連するメモがないか確認します。メモリを情報源とする内容のずれを見つけた場合は、コードベースを情報源とする証拠とは別に報告し、証拠セクションで「(auto memory [claude])」とタグ付けしてください。このブロックがコンテキストに存在しない場合は、この確認を省略してください。

サブエージェントには、次の2つの役割があります。

1. 調査サブエージェント — 読み取り専用です。ファイルの編集、後継の作成、削除を行ってはいけません。それぞれが、ファイルパス、証拠、推奨するアクション、確信度、未解決の質問を返します。成果物が独立している場合は、並列実行できます。
2. 置換サブエージェント — 古くなった学習内容を置き換える、新しい学習内容を1件だけ作成します。これらは一度に1つずつ順次実行します（各置換サブエージェントは、重要なコードを読む必要がある場合があり、複数を並列実行するとコンテキストを使い果たすおそれがあります）。各置換が完了した後、オーケストレーターがすべての削除とメタデータの更新を行います。

オーケストレーターは、調査結果を統合し、矛盾を検出し、置換サブエージェントを調整し、すべての削除とメタデータの編集を一元的に行います。対話モードでは、判断が難しいケースについてユーザーに質問します。自動修正モードでは、判断が難しいケースを古いものとしてマークします。2つの成果物に重複がある場合や、同じ根本的な問題を扱っている場合は、並列化せずにまとめて調査してください。

フェーズ2：適切な保守アクションを分類する

証拠を収集したら、推奨するアクションを1つ割り当てます。

維持

学習内容は現在も正確で有用です。ファイルを編集せず、レビュー済みで信頼性が保たれていることを報告してください。別の理由で意味のある更新をすでに行う場合に限り、last_refreshed を追加します。

更新

中核となる解決策は今も有効ですが、参照先（パス、クラス名、リンク、コードスニペット、メタデータ）が古くなっています。直接修正してください。

統合

フェーズ 1.75 で、内容が大きく重複しているものの、どちらも実質的に正しいドキュメントが特定された場合は、統合を選択してください。これは、単一のドキュメントの古くなった箇所を修正する「更新」や、誤解を招くガイダンスを書き直す「置換」とは異なります。「どちらも正しいが、一方がもう一方を包含している」場合に、統合を行います。

統合する場合：

• 2 つのドキュメントが同じ問題を説明し、同じ（または互換性のある）解決策を推奨している
• 一方のドキュメントが限定的な先行版で、より新しいドキュメントが同じ内容をより広く扱っている
• 統合対象のドキュメントにしかない内容を、正規のドキュメントのセクションまたは補足として収められる
• 両方を残すと、検索上のメリットがほとんどない一方で、内容のずれが生じるリスクがある

統合しない場合（フェーズ 1.75 の検索価値テストを適用してください）：

• ドキュメントがそれぞれ独立して検索されるような、実質的に異なるサブ問題を扱っている
• 統合すると、ずれによる正確性の損失リスクよりも、ナビゲーションへの悪影響が大きい扱いにくいドキュメントになる

統合と削除の違い： 統合対象のドキュメントに、残す価値のある独自の内容（例外的なケース、別のアプローチ、追加の予防ルール）がある場合は、まず「統合」でその内容をまとめてください。統合対象のドキュメントに、正規のドキュメントにすでに記載されていない内容がなければ、そのまま「削除」に進んでください。

「統合」の操作は、統合対象のドキュメントにしかない内容を正規のドキュメントにまとめ、その後、統合対象のドキュメントを削除することです。アーカイブではなく、削除してください。Git の履歴に残ります。

置換

学習内容の中核となるガイダンスが誤解を招くものになっている場合は、置換を選択してください。推奨される修正方法が大きく変わった、根本原因やアーキテクチャが変化した、または推奨されるパターンが異なる場合が該当します。

ユーザーが元の学習内容を書いてから数か月後に更新を依頼している場合もあります。ユーザーには残っていそうにない置換のための情報を尋ねず、エージェントの知見を活用してコードベースを調査し、置換内容をまとめてください。

証拠の評価：

置換候補を特定するまでに、フェーズ 1 の調査ですでに重要な証拠を収集しています。古い学習内容の主張、現在のコードの実際の動作、ずれが生じた箇所です。この証拠が、信頼できる置換内容を書くのに十分かどうかを評価してください。

• 証拠が十分 — 古い学習内容の推奨事項と現在のアプローチの両方を理解している。調査によって、現在のコードパターン、新しいファイルの場所、変更後のアーキテクチャが判明した。→ 置換内容の作成に進んでください（フェーズ 4 の置換フローを参照）。
• 証拠が不十分 — ずれがあまりにも根本的で、現在のアプローチを自信を持って文書化できない。サブシステム全体が置き換わっている、またはファイルの確認だけでは新しいアーキテクチャが複雑すぎて理解できない。→ その場で古い内容としてマークしてください：
  • フロントマターに status: stale、stale_reason: [what you found]、stale_date: YYYY-MM-DD を追加する
  • 見つかった証拠と、不足している情報を報告する
  • その領域に次に取り組み、新たな問題解決の知見が得られた後で ce:compound を実行するようユーザーに提案する

削除

以下の場合は削除を選択してください。

• コードやワークフローがすでに存在せず、問題領域もなくなっている
• 学習内容が古くなっており、文書化する価値のある現代的な代替内容もない
• 学習内容が別のドキュメントと完全に重複している（先に統合すべき独自の内容がある場合は「統合」を使用する）
• 置換すべきことを示す、有意義な後継の証拠がない

操作：ファイルを削除します。アーカイブ用ディレクトリもメタデータも必要ありません。削除するだけです。復元が必要になった場合も、Git の履歴に削除されたファイルがすべて残っています。

削除する前に、問題領域がまだ存在するか確認する

学びが参照しているファイルがなくなっているのは有力な証拠ですが、それは実装がなくなったことを示すにすぎません。削除する前に、その学びが解決する問題が今もコードベースで課題になっているかを考えてください。

• セッショントークンの保存に関する学びで、auth_token.rb がなくなっている場合、アプリケーションは今もセッショントークンを扱っていますか？扱っているなら、実装が変わっても概念は残っています。これは「置き換え」であり、「削除」ではありません。
• 非推奨の API エンドポイントに関する学びで、機能全体が削除されている場合、問題領域はなくなっています。これは「削除」です。

以前の学びに含まれていたキーワードを機械的に検索しないでください。まず、その学びがどのような問題に対処しているのかを理解し、その問題領域が今もコードベースに存在するかを調べてください。エージェントは概念を理解できます。その理解を活用し、以前のコードがあった場所ではなく、現在その問題が存在する場所を探してください。

実装と問題領域の両方がなくなっている場合に限り、自動的に削除してください。

• 参照されているコードがなくなっており、アプリケーションもその問題領域を扱わなくなっている
• 学びが明らかに優れた後継資料に完全に置き換えられており、古いドキュメントに独自の価値がない
• ドキュメントが明らかに重複しており、正本となるドキュメントにすでに記載されている内容しかない

実装がなくなっていても問題領域が残っている場合（アプリが引き続き認証、決済処理、マイグレーションを行う場合など）は、「置き換え」と分類してください。問題は依然として重要であり、現在の方法を文書化すべきです。

一般的なアドバイスが「今も妥当」だからという理由だけで、学びを残さないでください。参照先の具体的なコードがなくなっているなら、その学びは読者を誤解させます。しかし、問題領域が今も存在する学びを削除しないでください。その知識の不足を補うため、後継資料を作成する必要があります。

パターンに関する指針

パターンドキュメントにも同じ5つの判断（維持、更新、統合、置き換え、削除）を適用します。ただし、インシデント単位の学びではなく、そこから導かれる指針として評価してください。主な違いは次のとおりです。

• 維持：基となる学びが引き続き一般化されたルールを裏付けており、例も依然として代表的である
• 更新：ルールは有効だが、例、リンク、対象範囲、または裏付けとなる参照情報が古くなっている
• 統合：2つのパターンドキュメントが同じ一連の学びを一般化している、または同じ設計上の懸念を扱っているため、1つの正本となるパターンに統合する
• 置き換え：一般化されたルールが誤解を招くようになった、または基となる学びから異なる統合的な見解が導かれる。更新済みの学びに基づいて置き換え、推測で新しいルールを作らない
• 削除：そのパターンが無効になった、繰り返し発生しなくなった、または固有の内容を残さず、より強力なパターンドキュメントに完全に包含されている

フェーズ3：判断を確認する

自動修正モード

**このフェーズ全体をスキップしてください。質問をしたり、選択肢を提示したり、入力を待ったりしないでください。**フェーズ4に直接進み、フェーズ2の分類に基づいてすべての操作を実行してください。

• 判断が明確な「維持」「更新」「統合」「自動削除」、および十分な根拠がある「置き換え」→ そのまま実行する
• 判断が曖昧なケース → 古いものとしてマークする
• その後、レポートを生成する（「出力形式」を参照）

対話モード

ほとんどの更新と統合は、質問せずに直接適用してください。ユーザーに確認するのは、次の場合に限ります。

• 適切な対応が本当に曖昧である（更新、置き換え、統合、削除のいずれか）
• ドキュメントを削除しようとしており、根拠が明確でない場合（フェーズ2の自動削除の条件を参照）。自動削除の条件を満たしている場合は、確認せずに進めてください。
• 統合しようとしており、正本とするドキュメントを明確に選べない場合
• 置き換えによって後継資料を作成しようとしている場合

コード変更が意図的だったか、ユーザーがコードのバグ修正を望んでいるか、またはドキュメント保守以外の懸念について質問しないでください。担当範囲を守り、ドキュメントの正確性に集中してください。

質問の形式

利用可能な場合は、必ずプラットフォームの選択式質問ツールを使って選択肢を提示します（Claude Code では AskUserQuestion、Codex では request_user_input、Gemini では ask_user）。それ以外の場合は、番号付きの選択肢をプレーンテキストで提示し、ユーザーの返答を待ってから先に進みます。

質問のルール：

• 一度に質問は 1 つ
• 選択式を優先
• 推奨する選択肢を先に提示
• 推奨する理由を簡潔な一文で説明
• 実際には選択肢にならない行動をユーザーに選ばせない

対象を絞った範囲

単一の成果物について、以下を提示します。

• ファイルパス
• 根拠を示す箇条書き 2～4 項目
• 推奨する対応

その後、次の質問をします。

This [learning/pattern] looks like a [Keep/Update/Consolidate/Replace/Delete].

Why: [one-sentence rationale based on the evidence]

What would you like to do?

1. [Recommended action]
2. [Second plausible action]
3. Skip for now

5 つすべての対応が本当に妥当な選択肢である場合を除き、5 つすべてを列挙しないでください。

バッチ範囲

複数の学びについて：

1. 明らかな 保持 ケースをまとめる
2. 修正が簡単な明らかな 更新 ケースをまとめる
3. 正本となるドキュメントが明確な 統合 ケースをまとめる
4. 置換 ケースは個別に、またはごく少数のグループにまとめて提示する
5. 削除 ケースは、自動削除の候補として有力な場合を除き、個別に提示する

段階的に確認を求めます。

1. 保持／更新の推奨事項をまとめて確認する
2. 次に統合グループを扱う（正本となるドキュメントと統合対象を提示する）
3. 次に置換を 1 件ずつ扱う
4. 次に削除を、削除が明白かつ安全で自動適用できる場合を除き、1 件ずつ扱う

メンテナンス項目を一度にすべて提示しないでください。

フェーズ 4：選択した対応を実行する

保持のフロー

デフォルトではファイルを編集しません。その学びが引き続き信頼できる理由を要約します。

更新のフロー

解決策が実質的に正しい場合に限り、既存箇所を編集します。

有効な既存箇所の更新例：

• app/models/auth_token.rb の参照を app/models/session_token.rb に変更する
• module: AuthToken を module: SessionToken に更新する
• 関連ドキュメントへの古いリンクを修正する
• ディレクトリ移動後に実装メモを更新する

既存箇所の更新として行うべきではない例：

• 理解に影響しない誤字の修正
• 文体だけを目的とした文章の言い換え
• 正確さや使いやすさを実質的に向上させない、小規模な整理
• 古い修正内容が現在ではアンチパターンになっている
• システムのアーキテクチャが大きく変わり、古いガイダンスが誤解を招く
• トラブルシューティングの手順が実質的に異なる

これらの場合は、更新ではなく置換が必要です。

統合フロー

オーケストレーターが統合を直接処理します（ドキュメントはすでに読み込まれており、マージは対象を絞った編集なので、サブエージェントは不要です）。統合候補はトピッククラスターごとに処理します。Phase 1.75 で特定した各クラスターについて、次の手順に従います。

1. 正規ドキュメントを確認する — クラスター内で、より範囲が広く、より最新で、より正確なドキュメントです。
2. 統合対象のドキュメントから独自の内容を抽出する — 正規ドキュメントがまだカバーしていない内容です。具体的なエッジケース、追加の予防ルール、別のデバッグ方法などが該当します。
3. 独自の内容を正規ドキュメントにマージする — 自然な場所に組み込みます。単に末尾へ追加しないでください。論理的に適切な場所に統合します。独自の内容が小さい場合（箇条書きや一文など）は、文中に組み込みます。実質的なサブトピックである場合は、明確な見出しを付けたセクションとして追加します。
4. 相互参照を更新する — ほかのドキュメントが統合対象のドキュメントを参照している場合は、参照先を正規ドキュメントに変更します。
5. 統合対象のドキュメントを削除する。 アーカイブしたり、リダイレクトメタデータを追加したりせず、ファイルをそのまま削除します。Git の履歴に内容は残ります。

ドキュメントクラスターに、重複するドキュメントが 3 つ以上ある場合は、ペアごとに処理します。まず、最も重複する 2 つのドキュメントを統合してから、統合後の内容を次のドキュメントと統合すべきか判断します。

マージ以外の構造変更： 統合には逆のケースも含まれます。1 つのドキュメントが扱いにくいほど大きくなり、個別に検索できると便利な複数の異なる問題を扱っている場合は、分割を提案してもかまいません。サブトピックが本当に独立しており、メンテナーが一方だけを検索する可能性がある場合に限り、分割してください。

置換フロー

置換候補は一度に 1 つずつ、順番に処理します。メインのコンテキストウィンドウを保護するため、各置換はサブエージェントが作成します。

置換が必要な場合は、ドキュメントの契約ファイルを読み込み、その内容を置換サブエージェントのタスクプロンプトに渡します。

• references/schema.yaml — フロントマターのフィールドと列挙値
• references/yaml-schema.md — カテゴリのマッピング
• assets/resolution-template.md — セクション構成

置換サブエージェントに、記憶を頼りにフロントマターのフィールド、列挙値、セクションの順序を考案させないでください。

証拠が十分な場合：

1. 置き換える学習内容を作成するサブエージェントを 1 つ起動します。次の情報を渡してください。
   • 古い学習内容の全文
   • 調査で得られた証拠の要約（何が変わったか、現在のコードがどのように動作するか、古いガイダンスが誤解を招く理由）
   • 対象パスとカテゴリ（カテゴリ自体が変わっていない限り、古い学習内容と同じカテゴリ）
   • 上記の 3 つのサポートファイルの関連内容
2. サブエージェントは、サポートファイルを信頼できる情報源として、新しい学習内容を作成します。フロントマターのフィールドと列挙値には references/schema.yaml、カテゴリのマッピングには references/yaml-schema.md、セクションの順序には assets/resolution-template.md を使用してください。渡された情報以外のコンテキストが必要な場合は、専用のファイル検索ツールと読み取りツールを使用してください。
3. サブエージェントの作業が完了した後、オーケストレーターが古い学習ファイルを削除します。新しい学習内容のフロントマターには、追跡可能性のために supersedes: [old learning filename] を含めてもかまいませんが、必須ではありません。Git の履歴とコミットメッセージで同じ情報を確認できます。

証拠が不十分な場合：

1. 学習内容をその場で古いものとしてマークします。
   • フロントマターに追加します：status: stale、stale_reason: [what you found]、stale_date: YYYY-MM-DD
2. 見つかった証拠と不足している内容を報告します。
3. その領域に次に遭遇した後、ce:compound を実行するようユーザーに勧めます。

削除フロー

学習内容が明らかに古くなっている場合、重複していてマージする独自の内容がない場合、または対象の問題領域がなくなっている場合に限り、削除してください。古いという理由だけでドキュメントを削除しないでください。経過年数だけでは削除の判断材料になりません。

出力形式

レポート全体を Markdown 形式で出力する必要があります。 調査結果を内部で要約してから一行だけ出力してはいけません。レポートそのものが成果物です。すべてのセクションを、見出し、表、箇条書きを使って読みやすい Markdown 形式で出力してください。

選択した対象範囲の処理後、次のレポートを出力してください。

Compound Refresh Summary
========================
Scanned: N learnings

Kept: X
Updated: Y
Consolidated: C
Replaced: Z
Deleted: W
Skipped: V
Marked stale: S

その後、処理したすべてのファイルについて、次の項目を記載してください。

• ファイルパス
• 分類（Keep／Update／Consolidate／Replace／Delete／Stale）
• 確認された根拠。メモリ由来の調査結果には、コードベース由来の根拠と区別できるように「(auto memory [claude])」を付けてください
• 実施した措置（または推奨する措置）。Consolidate の場合は、正規ドキュメント、統合した固有の内容、削除した内容を記載してください

Keep の結果は、変更せずにレビューしたセクションに記載し、Git の差分を発生させずに結果がわかるようにしてください。

Autofix モードのレポート

Autofix モードでは、レポートだけが成果物です。追加の質問をするユーザーはいないため、レポートは単独で完結していなければなりません。レポート全体を出力してください。省略、要約、セクションの省略はしないでください。

措置を次の2つのセクションに分けてください。

適用済み（書き込みに成功した変更）：

• 更新したファイルごとに、ファイルパス、修正した参照先、その理由
• 統合したクラスターごとに、正規ドキュメント、各統合対象ドキュメントから取り込んだ固有の内容、削除した統合対象ドキュメント
• 置換したファイルごとに、以前の学習内容が推奨していたことと、現在のコードが実行することの違い、および後継ドキュメントのパス
• 削除したファイルごとに、ファイルパスと削除理由（対象の問題領域がなくなった、完全に重複しているなど）
• 古い情報としてマークしたファイルごとに、ファイルパス、確認された根拠、判断が曖昧な理由

推奨（権限拒否など、書き込みできなかった措置）：

• 上記と同じ詳細を、人が実施するための推奨として記載してください
• ユーザーが手作業で変更を適用するか、スキルを対話形式で再実行できるよう、十分な情報を含めてください

すべての書き込みに成功した場合、「推奨」セクションは空にしてください。書き込みが一つも成功しなかった場合（読み取り専用での実行など）は、すべての措置を「推奨」に記載してください。この場合、レポートは保守計画になります。

レガシーのクリーンアップ（docs/solutions/_archived/ が存在する場合）：

• 見つかったアーカイブ済みファイルを列挙し、それぞれの扱いを推奨してください。引き続き関連性がある場合は復元、完全に古くなっている場合は削除、アクティブなドキュメントと重複している場合は統合とします。

フェーズ 5：変更のコミット

すべての措置を実行し、レポートを生成した後、変更のコミットを処理してください。ファイルが変更されていない場合（すべて Keep、またはすべての書き込みが失敗した場合）は、このフェーズをスキップしてください。

Git の状況を確認する

選択肢を提示する前に、次の点を確認してください。

1. 現在チェックアウトされているブランチ（main/master かフィーチャーブランチか）
2. compound-refresh が変更した内容以外に、未コミットの変更が作業ツリーにあるか
3. リポジトリのコミットスタイルに合わせるため、最近のコミットメッセージ

Autofix モード

適切な既定値を使用してください。質問できるユーザーはいません。

状況	既定のアクション
main/master 上	更新内容にちなんだ名前のブランチ（例：docs/refresh-auth-and-ci-learnings）を作成し、コミットして、PR の作成を試みます。PR の作成に失敗した場合は、ブランチ名をレポートに記載してください。
フィーチャーブランチ上	現在のブランチに別のコミットとしてコミットします
Git 操作が失敗	推奨する Git コマンドをレポートに記載して続行します

ステージングするのは、compound-refresh が変更したファイルだけにしてください。作業ツリー内の他の変更はステージングしないでください。

対話モード

まず、git branch --show-current を実行して現在のブランチを確認します。その結果に基づいて、適切な選択肢を提示します。ユーザーがどの選択肢を選んでも、ステージングするのは compound-refresh のファイルのみです。

現在のブランチが main、master、またはリポジトリのデフォルトブランチの場合：

1. ブランチを作成し、コミットして、PR を作成する（推奨）— ブランチ名は汎用的なものではなく、更新した内容が具体的に分かる名前にしてください（例：docs/refresh-auth-learnings。docs/compound-refresh ではありません）
2. {current branch name} に直接コミットする
3. コミットしない — 自分で対応します

現在のブランチがフィーチャーブランチで、作業ツリーがクリーンな場合：

1. {current branch name} に別コミットとしてコミットする（推奨）
2. 別のブランチを作成してコミットする
3. コミットしない

現在のブランチがフィーチャーブランチで、作業ツリーに未コミットの変更がある場合：

1. compound-refresh の変更のみを {current branch name} にコミットする（選択的にステージングし、他の変更があるファイルには手を加えない）
2. コミットしない

コミットメッセージ

次の条件を満たす、内容が分かるコミットメッセージを書いてください。

• 何を更新したかを要約する（例：「古くなった学習内容を3件更新し、重複するドキュメントを2件統合し、不要なドキュメントを1件削除」）
• リポジトリ既存のコミット規約に従う（最近の git log でスタイルを確認してください）
• 簡潔にする — 詳細は変更したファイルに記載されています

ce:compound との関係

• ce:compound は、新たに解決して検証した問題を記録します
• ce:compound-refresh は、コードベースの進化に合わせて古い学習内容を保守します。個々の正確性と、ドキュメント一式としての全体的な構成の両方が対象です

信頼できる後継ドキュメントを書くのに十分な実証的根拠がある場合にのみ、置き換えを行ってください。根拠が不十分な場合は、古くなったことを明記し、ユーザーが次にその問題領域に遭遇した際に ce:compound を推奨してください。

ドキュメント一式が自然に増えて冗長さが生じている場合は、積極的に統合してください。ce:compound を実行するたびに新しいドキュメントが追加されます。時間の経過とともに、複数のドキュメントが少しずつ異なる視点から同じ問題を扱うことがあります。定期的に統合することで、ドキュメント一式を簡潔で信頼できる状態に保てます。

発見可能性の確認

更新レポートを生成した後、プロジェクトの指示ファイルを読むエージェントが、ドキュメント化された領域で作業を始める前に docs/solutions/ を見つけて検索できるか確認します。この確認は毎回行います。ナレッジストアの価値が積み重なるのは、エージェントがその存在を見つけられる場合に限られるためです。この確認によって編集が必要になった場合は、以下の手順5を参照し、フェーズ5のコミットフローの一部として、またはその直後にコミットします。

1. ルートレベルに存在する指示ファイル（AGENTS.md、CLAUDE.md、または両方）を特定します。ファイルを読み、どれに実質的な内容が含まれているかを判断してください。一方のファイルが、もう一方を @ で読み込むだけのシムになっている場合があります（例：CLAUDE.md の内容が @AGENTS.md のみ、またはその逆）。実質的な内容があるファイルを評価・編集の対象とし、シムは無視してください。どちらのファイルも存在しない場合は、この確認全体を省略します。

2. 指示ファイルを読んだエージェントが、次の3点を把握できるか評価します。

   • ドキュメント化された解決策を検索できるナレッジストアがあること
   • 効果的に検索するのに十分な構造の情報（カテゴリ別の構成、module、tags、problem_type などの YAML フロントマターのフィールド）
   • いつ検索すべきか（ドキュメント化された領域で機能を実装したり、問題をデバッグしたり、判断を下したりする前 — 学習内容はバグ、ベストプラクティス、ワークフローのパターン、その他の組織的な知見を扱う場合があります）

   これは文字列一致ではなく、意味に基づく評価です。情報はアーキテクチャのセクションの1行や、落とし穴のセクションの箇条書きとして記載されていたり、複数箇所に分かれていたり、正確なパス docs/solutions/ を一度も使わずに表現されていたりする場合があります。判断してください。エージェントがファイルを読んでナレッジストアを見つけ、活用すると合理的に考えられる場合は、この確認に合格です。

3. すでに意図が満たされている場合は、何もする必要はありません。

4. 満たされていない場合： a. ファイルの既存の構成、トーン、情報量に基づいて、言及を自然に追加できる場所を特定します。新しいセクションを作成する前に、その情報を最も関連性の高いセクション（アーキテクチャツリー、ディレクトリ一覧、ドキュメントのセクション、規約のブロックなど）に1行で追加できないか確認します。既存のセクションへの追記は、ほとんどの場合、新しい見出し付きセクションを作るより適切です。ファイルが明確なセクション構成になっていて、少しでも関連する箇所がない場合に限り、最後の手段として新しいセクションを追加します。 b. 3つの要素が伝わる、最小限の追記を作成します。ファイルの既存のスタイルと情報量に合わせます。追記ではプラグインではなく、ナレッジストア自体について説明します。

   トーンは説明的にし、指示的にならないようにします。タイミングは指示ではなく説明として表現します。「実装前またはデバッグ前に確認してください」ではなく、「ドキュメントに記載された領域の実装やデバッグ時に関連します」とします。「実装前に必ず検索してください」のような命令形の指示は、ワークフローに専用の検索手順がすでに含まれている場合、読み込みが重複する原因になります。目的は存在を知らせることです。エージェントがそのフォルダーの存在と内容を把握し、参照するタイミングは自ら判断できるようにします。

   調整例（テンプレートではありません。ファイルに合わせて調整してください）：

   既存のディレクトリ一覧やアーキテクチャセクションがある場合は、1行追加します：

   docs/solutions/  # 過去の問題（バグ、ベストプラクティス、ワークフローのパターン）に対する解決策を、YAML frontmatter（module、tags、problem_type）を付けてカテゴリ別に記録
   

   ファイル内に自然に追加できる箇所がない場合は、小さな見出し付きセクションを追加します：

   ## ドキュメント化された解決策
   
   `docs/solutions/` — 過去の問題（バグ、ベストプラクティス、ワークフローのパターン）に対する解決策を、YAML frontmatter（`module`、`tags`、`problem_type`）を付けてカテゴリ別に記録しています。ドキュメントに記載された領域の実装やデバッグ時に関連します。
   

   c. 対話モードでは、これが重要な理由をユーザーに説明します。新しいセッション、他のツール、プラグインを使わない共同作業者を含め、このリポジトリで作業するエージェントは、指示ファイルに記載がなければ docs/solutions/ を確認することを知りません。提案する変更内容と追加箇所を示し、プラットフォームのブロッキング質問ツール（Claude Code では AskUserQuestion、Codex では request_user_input、Gemini では ask_user）を使って、編集前に同意を得ます。質問ツールを利用できない場合は、提案を提示してユーザーの返答を待ちます。自動修正モードでは、レポートに「Discoverability recommendation」の行として追加します。指示ファイルの編集は試みません（自動修正の対象範囲はドキュメントの保守であり、プロジェクト設定ではありません）。

5. チェックによって編集が発生した場合は、既存のコミットを修正するか、後続コミットを作成します。 手順4で指示ファイルを編集し、フェーズ5ですでに更新内容をコミットしている場合は、編集したファイルをステージングし、（同じブランチ上にいて、まだプッシュしていない場合は）既存のコミットを修正するか、小さな後続コミット（例：docs: add docs/solutions/ discoverability to AGENTS.md）を作成します。フェーズ5ですでにブランチをリモートにプッシュしている場合（例：ブランチとPRの手順）は、後続コミットもプッシュし、開いているPRに見つけやすさに関する変更を含めます。これにより、実行終了時に作業ツリーがクリーンな状態になり、リモートとの同期も保たれます。フェーズ5でユーザーが「コミットしない」を選択した場合は、他の未コミットの更新内容とともに、指示ファイルの編集をステージングせずに残します。個別のコミット処理は不要です。