close-roadmap

ロードマップをクローズする

ユーザー向け機能の一連の作業を締めくくります。実行は完了しています。 ROADMAP.final.md または PLAN.final.md の承認を受けて実装が完了し、 docs/<feature>/（別の場所を使っていない場合は、プロジェクトの計画用フォルダー）に、そこに至るまでの計画ドキュメント、レビュー記録、実行成果物が保管されています。そのままにしておくと、次のエージェントが最初に読み、最も信頼するフォルダーになりますが、その大半はもう事実ではありません。あなたの仕事は、存在するもの（プロジェクトのエージェント向け案内から1ステップでたどれる、正規かつ最新の情報）と、まだ残っているもの（次のロードマップのrev1）だけを残すことです。

新しいエージェントがツリーだけを読んで、この機能についての真実を最少の手数で把握できるか、また最終ドキュメントで約束されたすべての項目を、実装済み、次回に引き継ぎ、延期、またはユーザーの判断で取り下げ済みのいずれかとして、今も確認できるかによって評価されます。

自分の判断で作業を取り下げてはいけません。 最終ドキュメントで約束された計画は、プロダクト上のコミットメントです。実装されていない場合、ユーザーが別の判断をしない限り、次のロードマップに引き継ぎます。ユーザーが別の判断をした場合は、プロジェクトの延期作業記録（なければフォルダーのREADMEに「Deferred」セクションを設けます）に理由とともに記録し、後から暗黙のうちに判断が覆されないようにします。

判断を記録するときに、新たな判断をしてはいけません。 すでに下された判断を判断記録に残すのはあなたの仕事ですが、新たな判断を下すのはあなたの仕事ではありません。記録が曖昧な場合（理由が記されていない実行時の変更、ユーザーから回答がなかった質問の記録など）は、簡潔な言葉で、質問ごとに1つの判断を尋ねてください。

入力

機能名は引数から取得します（例：/close-roadmap notifications）。 docs/<feature>/ の内容をすべて読み、その後、次の順に確認します。

1. 最終ドキュメント — ROADMAP.final.md または PLAN.final.md（機能にあれば TECHNICAL.final.md または EXPERIENCE.final.md も）。 rev版しかない場合は、ここで停止します。承認されたものがないため、クローズするものもありません。
2. 実行記録 — EXECUTION.md（実装された内容とコミットハッシュ）、質問ログ（変更内容と未回答の質問。プロジェクト内で保管されている場所は問いません）、ACCEPTANCE.md（人が手動で確認するよう求められた内容）、HANDOFF.md（次のエージェントへの引き継ぎ）、および未テスト項目のリストやテスト計画。これらは事実ではなく主張です。次の手順で確認し、トリアージの前に ACCEPTANCE.md 自体もレビューします。
3. コードと履歴。 ブランチの git log と、EXECUTION.mdに記載されたコミットを確認します。次に、完了と記載されたすべての計画について、実際のコードを確認します。計画が実装済みなのは、ドキュメントにそう書かれているからではなく、コードが計画の検証手順どおりに動作するときです。 計画と異なる形で実装されたものは、食い違いとして取り繕うのではなく、判断事項として扱います（「実装された作業」を参照）。
4. この機能が関係する正規ドキュメント — プロジェクトのドキュメントマップ（たとえば、各種ドキュメントの保管場所を示す AGENTS.md や CONTRIBUTING.md の表）が指定するアーキテクチャ、データモデル、運用、ユーザーガイド、プロダクトのステータスの各ドキュメント、およびドキュメント索引に機能固有の項目があればそれも確認します。書き込む前にこれらを読み、重複した内容を追加するのではなく、既存の関連記述と並ぶ形で追記してください。
5. プロジェクト内ですでにクローズされた機能のフォルダーを確認し、成果物の構成をそろえます。

兄弟スキルと同様に、メインの統合ブランチとの差分を確認します（git fetch を実行し、git log --oneline <branch>..<main> を確認します。<main> は main や dev などです）。変更後のツリーを確認せずにロードマップをクローズすると、すでに存在しない状態を文書化することになります。その場合は、その旨を伝え、マージする前に確認してください（merge-branch を参照）。

受け入れレビュー — トリアージの前に完了させる

ACCEPTANCE.md は、担当者が手作業で確認するよう依頼されたチェックリストです （write-acceptance を参照）。これらのチェックは機械では実行できないため、 記録の中でコードを読むだけでは確認できない唯一の項目です。各チェックを一つずつ確認し、 それぞれに結果を付けてください。

結果	意味	対応
passed	ユーザーまたはテスターが、指定された観察可能な結果を報告した	その計画の landed 判定の根拠として記載する
failed	別の結果が報告された	計画は landed ではなく pending です。V2 rev1 に確認された内容を記載します
never run	結果が一度も報告されていない	確認します。回答があるまで landed ではありません

未実行のチェックは未検証の作業であり、landed の作業ではありません — 検証手順が実行されていない計画と同じ扱いです。コードが正しく見えるからといって、ひそかに landed に昇格させないでください。コードを読むだけでは判断できないからこそ、そのチェックリストに含まれていました。チェックごとに一つずつ質問し、今すぐ実行するか、未検証のまま受け入れるかをユーザーに尋ねます。未検証のまま受け入れる場合は、プロジェクトで現在動作している内容を記録している箇所すべてで partial としてマークし、検証を V2 rev1 の計画に追加します。

結果は、以下の台帳の根拠欄に記載してください。また、緑色のテストスイートではなく、担当者の確認に基づいて landed と判定した計画をレポートに明記します。この機能の完了後も実施する価値があるチェック（1回限りの受け入れ確認ではなく、回帰チェック）は、ACCEPTANCE.md を削除する前に、その機能の有効なテスト計画へ移します。

トリアージ — ファイルに手を加える前に内容を確認する

最終ドキュメント内のすべてのマイルストーンと計画、質問ログのすべての項目、未テスト項目の一覧、テスト計画には、それぞれ次の4つの判定のうち、ちょうど1つを付けます。

判定	意味	記載先
landed	コードで検証され、コミットも確認済みであり、受け入れチェックがある場合はそれにも合格している	正式なドキュメント。計画の記述は削除します
pending	実装が約束されているが未実装、または一部のみ実装済み	元の ID を括弧内に添えて ROADMAP-V2.rev1.md に記載します
deferred	ユーザーが現時点では実装しないと決めた	保留作業の記録（内容、理由、判断が変わる条件）
dropped	ユーザーが実装しないと決めた	理由を添えて V2 rev1 の「Not carried forward」セクションに記載します

deferred または dropped を指定できるのはユーザーだけです。台帳は表形式で提示してください — ID、タイトル、判定、根拠（コミットハッシュまたはファイル）を含め、回答が必要な質問には印を付けます。そして、削除を行う前にユーザーの返答を待ってください。 台帳は、このスキルの成果物のうち、後からリポジトリのツリーだけでは再構成できない唯一のものです。そのため、コミットメッセージにも含めます。

まだ残っている作業 — docs/<feature>/ROADMAP-V2.rev1.md

rev1なのは、draft-roadmap のレビューサイクルに再び入るためです。rev2、rev3、ROADMAP-V2.final.md、そしてexecute-roadmapへと進みます。draft-roadmapの書き方に従い、すべての計画に適用されるそのスキルの継続的な要件も引き継いでください。

• 「Where this picks up」から始めます：前のロードマップで達成した内容について、繰り返すのではなくREADMEを参照しながら、また残っている作業について、優先度とその順序にした理由を示す1段落を書きます。負債（ユーザーに約束したものの、まだ実現していないこと）は機能より先に挙げます。
• 不変条件を引き継ぎます。 最終ドキュメントの実行契約、継続的な要件、不変条件はそのまま有効で、新しい計画はそれらに照らしてレビューされます。削除予定のファイルへのリンクではなく、内容をコピーしてください。
• 保留中のすべての計画で、入力、出力、検証手順を維持します。現状のコードに合わせて書き直してください。計画で挙げた接続箇所が移動している場合は、新しい場所を明記します。一部が実装済みの計画では、存在する部分と残りの作業を記し、実装済み部分があるファイルを示します。
• ログにある未回答の質問は、ユーザーが回答していないものをrev1の未解決のプロダクト上の質問として、それぞれ記録されている選択肢と推奨案を添えて記載します。回答済みのものは決定事項であり、ここではなく決定記録に記載します。
• **「Not carried forward」**には、ユーザーが取り下げた項目とその理由を記載し、ロードマップを意図的に縮小したことがレビュー担当者にわかるようにします。

実装済みの内容を再び記載してはいけません。rev1はREADMEを前提とします。

実装済みの作業 — 読まれる場所に記載する

プロジェクトのドキュメントマップに従って、実装済みの作業をそれぞれ適切な場所に記載します。機能フォルダーには、その機能だけに関する内容のみを置きます。他の領域を読む人にも必要な内容は、共有ページに記載します。

• 決定事項 → 決定記録（ADR）。プロジェクトで管理している場合は、決定ごとに1件作成します。 質問ログとEXECUTION.mdにある実行上の逸脱は、切迫した状況下で行われた決定であり、通常は決定記録に残されていません。理由がツリー内に残っているうちに、採用されなかった代替案も含めて記録してください。最終ドキュメントのレビュー時（「Responses to revN notes」）に確定し、現在のコードに反映されている決定事項も確認します。番号はプロジェクトの登録簿から取得します。別のブランチですでに番号が公開されている場合は、その番号を優先し、新しい項目に番号を振り直し、相互参照も更新します。プロジェクトに共通の登録簿がある場合、機能ごとの決定事項ファイルは作成しないでください。
• モデル → プロジェクトのデータモデルドキュメントに記載し、決定記録にリンクします。 共有ページに載せるべきではない独自のモデル（スキーマ、ワイヤーフォーマットなど）を持つ機能の場合は、そのフォルダー内に独自のデータモデルページを作成します。
• コードの構成とデータフロー → モジュールをまたぐ場合は共有アーキテクチャドキュメントに、機能独自の内部構造であればフォルダー内の ARCHITECTURE.md に記載します。 各ファイルでは、何が規範となるか（通常はコードの型）を示し、説明文とコードが食い違う場合はコードが正であり、説明文のほうが誤りだと明記します。
• 運用、API、イベント、設定、環境変数 — プロジェクトでそれらを文書化している場所に記載します。これらのドキュメントが生成される場合は、ジェネレーターを実行し、手作業で編集するのではなく、生成された成果物をコミットします。
• 人が行う操作 → ユーザーガイドに記載します。現在機能する内容 → プロジェクトの製品ステータスページに記載し、完了と一部完了を正直に区別します。テスト未実施の項目が残る計画は、誰かが検証するまで一部完了です。その検証はV2 rev1の計画に含めます。
• 見送ったコード → プロジェクトの技術的負債の記録に、内容、まだ対応していない理由、安全に対応できる条件を記載します。 EXECUTION.mdにある作業者の「Xには手を付けなかった。なぜなら……」という記述は、通常ここに該当します。
• 機能の手動テストとして引き続き使われる場合は、既知の不足点を最新の状態にして、手動テスト計画を残します。

共有ページにある内容を繰り返す要約ドキュメントは作成しないでください。READMEの役割は参照先を示すこと、共有ページの役割は内容を保持することです。

このフォルダーのREADME.md

docs/<feature>/README.mdを作成するか、書き直してください。

1. この機能が何であるかを一文で説明します。以降のすべてはこの一文を基点とし、続けてナビゲーション表を記載します。「知りたいこと → 読むページ」の形式で、ここにあるすべての内容について共通ページを示し、それ以外についてはこのフォルダー内のファイルを示してください。次のロードマップは1行にまとめます。
2. このフォルダーに含まれるものを、ファイルごとに1行で説明し、それぞれの用途も示します。歴史的な内容か規範的な内容かも含めてください。
3. 新しい作業の配置先を示します。フォルダーが再び不要なファイルであふれないようにする表です。決定事項は決定記録へ、モデルの変更はデータモデルのページへ、保留中の作業はロードマップへ、といった具合に整理します。
4. 現時点で存在するものをできるだけ簡潔に要約します。リンク先をたどらない読者のための説明であり、2つ目のアーキテクチャ文書にしてはいけません。

notes/は、専用のREADMEで歴史的な資料として位置づけます。各メモの内容、それに取って代わったもの、正しかった点と正しくなかった点を記載してください。メモはロードマップの出発点となった考察であるため残しますが、そこに規範的な内容はなく、実装の根拠として使ってはいけません。

ツリーで不要になったものを削除する

ユーザーが台帳を承認し、正式なドキュメントが作成されたら、次の作業を行います。

• 最終ドキュメント、すべての.revN.mdと.revN.notes.md、EXECUTION.md、機能の質問ログ、ACCEPTANCE.md、HANDOFF.md、未テスト項目のリストを削除します。 引き続き実施する価値のある受け入れチェックは、先に機能の現行テスト計画に移してください。再実行されないチェックはすでに役目を終えていますが、リグレッションチェックはそうではありません。各ラウンドの終了時にコミットされているため、反復の履歴はGitに残っています。ツリー内にコピーを残すと、エージェントが現行の内容と誤認します。archive/フォルダーに移してはいけません。それはパスを長くしただけの削除であり、そのフォルダーもいずれ不要なファイルであふれます。コミットメッセージには、削除した各ファイルと、その内容の移動先を記載します。
• 残すものは、README、V2 rev1、notes/、現行のテスト計画、計画で参照される設計やアセット、引用元となるファイルです。まずgrepで確認してください。ソースコードがドキュメントをファイル名で参照していることがあります。
• すべての参照元リンクを修正します。 削除または名前を変更したパスごとに、ドキュメント、エージェント向けの案内ファイル、README、ソースツリーをgrepで検索してください。ドキュメント索引にある機能の項目は、ロードマップではなくdocs/<feature>/README.mdを指すようにします。
• 生成ドキュメントを検証するテストと、最終ドキュメントに記載されている常設チェックを実行します。リンクチェッカーがない場合は、上記のgrepがリンクチェックになります。最後の名前変更を終えてから実行してください。変更前ではありません。

完了

• commit-changesに従い、完了処理を1つの変更としてコミットします。台帳、何をどこに記載したか、何を削除したか、その内容の移動先を含めてください。依頼されない限り、プッシュしてはいけません。V2 rev1も同じコミットに含めます。レビューラウンドは、draft-roadmapの指定どおり別々のコミットにします。
• プロダクトの言葉でユーザーに報告します。機能が現在どのように動作するか、何がどの順序で未完了か、完了時にユーザーが決定したこと、V2 rev1でレビュアーが最初に確認すべき箇所を伝えてください。