finalize-doc

計画またはロードマップを確定する

イテレーションが終了しました。改訂版はレビューされ、回答され、再レビューされ、最後にユーザーの承認を得ました。また、プロジェクトの計画フォルダー（別の場所を使用していない場合）である docs/<feature>/ には、すべての改訂版と各 .notes.md が保存されています。ユーザーが回答した質問と、選択に至った理由は、会話の中にしかありません。このままでは、フォルダーには古い文書が積み重なり、読者は決定事項を知るために文書同士を比較しなければなりません。また、決定の根拠の半分は、もう開けないチャットの中に残っています。

あなたは、<STEM>.final.md という1つの文書を作成します。新しいエージェントやユーザーがそれだけで読める文書です。承認された計画を承認どおりに記載し、その後に計画ができあがるまでの背景を記載します。何が問われ、何が回答され、改訂版の間で何が変わり、なぜ変わったのか、何が試され、取り下げられたのかを記録します。その後、最終版にすべての内容が引き継がれたため、改訂版とノートは削除します。

評価基準は2つです。承認済みの内容が最終版に反映される際に一切変更されていないこと、そして半年後に読んだ人が、Git の履歴をたどらなくても最終版から「なぜこうなっているのか？」に答えられることです。

決定事項を記録する際に、新たな決定をしてはいけません。 未解決の質問が残っている場合、その文書はまだ確定できる状態ではありません。作業を中断し、未解決の質問を伝えてください。最終版の作成は、履歴を添えたコピーであり、計画を改善する最後の機会ではありません。

承認なしに最終版を作成してはいけません。 「レビュアーから指摘がなかった」ことは、ユーザーの承認ではありません。会話または議論の中に承認の記録がない場合は、1行で確認を求め、返答を待ってください。

入力

引数で機能名を指定します（/finalize-doc webview）。フォルダーに複数のステムがある場合は、任意でステムも指定します（/finalize-doc webview TECHNICAL）。

1. 文書を探します。 docs/<feature>/ にある、最も番号の大きい <STEM>.revN.md を、ユーザーが別の版を指定していない限り、承認済みの改訂版として扱います。それ以前の <STEM>.revK.md と、すべての <STEM>.revK.notes.md を収集します。別のステムを使って並行して改訂された関連文書（プラットフォーム計画や実装文書など）も収集します。それぞれ同じ作業で独自の最終版を作成するか、作成対象から明示的に除外し、その理由を1行で記載します。
2. すべての改訂版とノートファイルを古い順に読みます。 「Responses to revN notes」セクションとレビュアーの決定表が履歴の骨格です。ノートにある指摘が質問となり、次の改訂版にある回答が答えとなります。
3. 会話を読みます。 ユーザーの回答は、ファイルではなくチャットで行われていることがよくあります。たとえば、改訂版への質問に対する番号付きの回答、途中でのスコープ変更、「はい、了解です」などです。これらは決定事項であり、日付とともに最終版に記録します。会話を参照できない新しいセッションの場合は、その旨を伝えます。記載できるのはファイルに残されている履歴であり、チャット内だけで決定されたことがないか、ユーザーに確認してもらう必要があります。
4. docs/<feature>/notes/* があれば読みます。ここには、イテレーション全体の基盤となったプロダクトの意図が記されています。最終版は、まずこの文書を参照するところから始めます。
5. 未解決事項がないことを確認します。承認済み改訂版の「Open questions」セクションが空であるか、すべて回答済みであること、また、最後のノートにあるレビュアーの指摘がすべて解決済みであること、理由を添えて取り下げられていること、またはユーザーによって実行段階に持ち越されていることを確認します。それ以外の事項があれば、最終版の作成を進めてはいけません。

最終文書 — <STEM>.final.md

次の順序で2つのパートを記載します。まず承認済みの計画を記載します。これは実行対象であり、execute-plan / execute-roadmap が読み込むものです。次に履歴を記載します。計画の背景を説明し、理由を問われたときに参照するものです。

パート 1 — 承認済みの計画

内容は承認済みの改訂版と同一で、変更点は次のとおりです。

• タイトルを <Feature> — <STEM>.final とし、冒頭の段落で承認内容を記載します。承認者、どの改訂版か、日付、最後のレビューで解決したレビュアーの指摘を明記します。
• 「改訂版Nの指摘への回答」セクションはこのパートから削除し、本来あるべきパート 2 に移します。
• 「未解決の質問」は、空なら削除します。ユーザーが承認時に最後の質問に回答した場合は「承認時に決定した事項」とし、それぞれの回答を決定事項の行として記録します。
• 以前の改訂版への参照（rev6 §4 のとおり、rev5 から変更なし）は解消します。これから削除する文書を最終版が参照してはいけません。参照先の文章を本文に含めるか、最終版だけで内容が完結するように書き換えます。最終版が改訂版より長くなるのはここだけですが、その価値はあります。
• ステータス列は日付とともに decided とし、proposed と記載される箇所がないようにします。

それ以外は何も変更しません。文章を引き締めたい、フェーズの順番を変えたい、足りないテストがあると思う場合、それらは最終版ではなく次の改訂版で扱います。本当にそのままでは成り立たない点（コードに矛盾する主張や、リンク切れなど）が見つかった場合は、黙って修正せず、作業を止めてユーザーに伝えてください。

パート 2 — ここに至るまで

会話を要約します。「なぜ当たり前の方法を選ばなかったのか」と尋ねる読者に向けて、次の順序で記述します。

1. 出発点。 メモの意図を 2〜3 文で述べ、それに対して改訂版 1 が何を提案したかを記します。ツリーに関して改訂版 1 が誤っていた点があれば、それも記します。「それはすでに存在する」「そのアカウントは存在しない」といった発見は、その後の全体の形を説明するためです。
2. 決定事項を 1 つの表にまとめる。 すべての改訂版とレビューを通じてユーザーに尋ねた質問を、尋ねた順に記載します。質問を 1 行で、質問者（作成者またはレビュアー、どの改訂版／メモか）、ユーザーの回答、日付、およびパート 1 のどの決定事項の行になったかを記載します。ユーザーが反復中にプロダクトのスコープを変更した場合も、その内容と、それによって不要になったものを明記した行として記載します。
3. 各ラウンド。 レビューラウンドごとに短い段落を 1 つ記します。レビュアーが見つけた点（指摘 ID ごと）、次の改訂版での対応、および次のラウンドに引き継がれた内容を記載します。ユーザーが退けた指摘は、その旨を記します。3 ラウンドにわたって残った指摘が、その後のスコープ変更で不要になった場合は、まさに残すべき経緯です。どれほどのコストがかかり、なぜ関係なくなったのかを記してください。
4. 試した後に取り下げたこと。 設計したものの削除した仕組み（整合性を保てなかったキャッシュ、スコープ変更によって不要になった方式など）について、それぞれ理由を記します。このセクションは、次のエージェントが同じ案を再提案するのを防ぐためのものです。
5. 意図的に後回しにしたこと。 計画に延期する項目のセクションがある場合は、繰り返すのではなくその箇所を示します。また、会話では延期したものの、計画に記載されなかった内容も追加します。

事実に基づいて、簡潔に記します。決定事項は 1 行、ラウンドは 1 段落です。ユーザーの発言がそのまま決定となった場合は、言い換えずに引用してください（「まずウィンドウ、その後タブ」、「わかりました、なし」など）。言い換えると意味がずれることがありますが、引用ならずれません。

関連文書

メインの計画と並行して反復した関連文書（メイン計画に併記するプラットフォーム固有の計画、ロードマップに併記する実装ドキュメントなど）がある場合は、その関連文書の最終版 <STEM2>.final.md を作成し、同じ 2 部構成にします。パート 2 は短くまとめ、共通する経緯についてはメインの最終版を参照します。メイン最終版のパート 1 からは関連文書の最終版にリンクし、関連文書の改訂版にはリンクしません。

rev と notes の削除

両方の最終版を書き、承認済みの rev と照合して再読したら、次の手順を実行します。

1. すべての <STEM>.revN.md と <STEM>.revN.notes.md、および関連するファイルの rev と notes を git rm で削除します。各ラウンドを終了したコミットの下に rev が git 履歴として残り、ツリーに残すのは最終版です。
2. すべての参照リンクを修正します。docs、エージェントのオリエンテーションファイル、skills を検索し、削除した各 stem を参照している箇所を確認します（例：grep -rn "<STEM>.rev" .）。rev を参照していた README や HANDOFF は、最終版を参照するようにします。
3. notes/ は絶対に削除しないでください。 プロダクトの notes は意図を記録したものであり、反復作業の成果物ではありません。
4. EXECUTION.md、ACCEPTANCE.md、HANDOFF.md、質問ログには手を加えないでください。これらは実行、および close-plan ／ close-roadmap に属します。

コミット

コミットは 1 つにします。最終版を追加し、rev と notes を削除して、リンクを修正します。コミットメッセージは commit-changes に従い、どの rev が誰によって承認されたか、履歴が最終版の Part 2 にあることを記載します。依頼されない限り、push はしないでください。

完了時

ユーザーには、作成した最終版、まとめて削除した rev と notes の数、会話でのみ決まっていて今回記録に残した判断、そして最終版にできなかったもの（未解決の質問や、含めなかった関連ファイル）とその理由を伝えます。その後、実行に引き継ぎます。execute-plan または execute-roadmap が最終版を読みます。レビュー担当者による最後の確認（review-doc の「最終版が現れたとき」）も、これを対象に実行できます。