product-roadmap

product-roadmap

このスキルの機能

4 つの真実のレイヤーにわたってプロダクトのマイルストーンの進捗を追跡します。「完了」は「タスク完了」よりも強い主張だからです。

レイヤー	問い	情報源
決定	決定・承認されましたか？	PDR のステータス（Proposed → Accepted → Completed）
実行	作業は完了しましたか？	MCP 経由の最新のイシュー状態（GitHub / GitLab / Jira / Linear）
証拠	コードで実際に確認できますか？	コードと PDR の照合（init のコンセプト）
ゲート	基準をクリアしましたか？	マイルストーンの PDR ゲートテーブル

マイルストーンは、4 つすべてのレイヤーがグリーンの場合にのみ進行中です。それ以外の場合は、「完了」の定義に関する警告が表示されます。

使用するタイミング

• 週次の進捗確認
• リリース前にマイルストーンの完了を確認するとき
• 四半期ごとのロードマップレビュー
• イシューをクローズした後、マイルストーンを昇格できるか確認するとき

使用しないタイミング

• PDR が存在しない場合（最初に /product-specify または /product-init を使用してください）
• PDR を作成する場合（/product-specify を使用してください）

実行手順

フェーズ A：PDR を読み込む

sh: scripts/bash/setup-product-roadmap.sh [--json]
ps: scripts/powershell/setup-product-roadmap.ps1

PDR ファイルを読み取ります（まずメモリを確認し、次にドラフトを確認します。メモリは共有レイアウトに従い、docs/adlc/memory/pdr/ に続いてレガシーの .adlc/memory/pdr/ も読み取ります）：

1. {REPO_ROOT}/docs/adlc/memory/pdr/PDR-*.md + レガシーの {REPO_ROOT}/.adlc/memory/pdr/PDR-*.md（Accepted/Completed）
2. {REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md（Proposed/Discovered）

マイルストーンを特定します：Category: Milestone の PDR が対象です。これらはロードマップの構造を定義し、### Gates テーブル、### Features Included テーブル、### Done Means の定義、および任意の ### Tracker Milestone URL を含みます。

フェーズ B：MCP 経由でイシューの状態を確認する

すべての PDR からイシューの URL を抽出します。完全な URL を含む ### Issues セクションを探します。

URL のホストからトラッカーを判定します：

URL のホスト	トラッカー	MCP ツールのパターン
github.com	GitHub	github_* MCP ツール
gitlab.com	GitLab	gitlab_* MCP ツール
*.atlassian.net	Jira	jira_* MCP ツール
linear.app	Linear	linear_* MCP ツール

イシューの状態を照会します — 各イシュー URL について、対応する MCP ツールを使用して状態（open/closed/in-progress）を取得します：

GitHub:   gh issue view NNN --json state,title,labels  (CLI fallback if MCP unavailable)
GitLab:   glab issue view NNN                            (CLI fallback)
Jira:     jira issue view ISSUE-KEY                      (CLI fallback)
Linear:   linear issue view ISSUE-ID                     (CLI fallback)

ネイティブのマイルストーンリンク — マイルストーンの PDR に ### Tracker Milestone URL がある場合：

• トラッカーからネイティブの進捗を直接取得します（クローズ数/合計数 + 期限）
• 実行状況の集計における正式な情報源として使用し、そのマイルストーンのイシューごとの照会は省略します

段階的な代替手段（MCP または CLI を利用できない場合）：

1. そのトラッカーの MCP ツールを試します
2. CLI（gh/glab/jira/linear）にフォールバックします
3. どちらも利用できない場合 → イシュー参照を「状態不明」として報告し、トラッカーごとに警告を 1 件表示します

イシューごとの実行状況：

状態	意味
closed / done	✅ 作業完了
open + 進行中ラベル/担当者あり	🔄 進行中
open + 担当者なし	⏳ 未着手

フェーズ C：コードと PDR の照合（Init のコンセプト）

コードが真実の情報源であり、PDR は主張です。コードに何も示されていないのに機能が完了とされている場合、乖離が生じています。

マイルストーン内の各機能 PDR について、コード上の証拠を確認します。

モード A — 明示的な証拠（推奨）：

• PDR の ### Evidence セクション（コードのパス/シンボルのリスト）を読み取ります
• 各パスの存在を確認します：test -f "{path}" または test -d "{path}"
• 状態：verified（すべてのパスが存在）｜stale（一部のパスが存在しない）｜missing（Evidence セクションがない）

モード B — ヒューリスティック（フォールバック、init 方式）：

• Evidence セクションがない場合 → product-init のディレクトリ検出ロジックを再利用します
• PDR の Feature-Area ディレクトリが存在するか確認します：test -d "src/{feature-area}/"
• 必要に応じて、コードベース内でタイトルのキーワードを grep します
• 信頼度は低く、「ヒューリスティックによる証拠」として報告します

引き継ぎルール：詳細な再発見はロードマップの担当範囲ではありません。「Completed」の項目で証拠が見つからない、または古くなっている場合、レポートには次のように記載します：「⚠️ コード上の証拠が見つかりません — 再発見するには /product-init を実行してください」。ロードマップでは簡易的な確認を行い、完全な発見は init の担当範囲です。

フェーズ D：ゲートの集計

各マイルストーン PDR の ### Gates テーブルを読みます。各ゲートについて、次のように確認します。

ゲートの種類	確認方法
engineering	関連するイシューの状態、または Evidence の検証状況を確認します
sign-off	承認の証拠があるか確認します（日付の記録、承認者の明記）
time	カットオーバー日からの経過日数を、必要な期間と比較します

ゲートの状態：green（基準を満たし、証拠が記録済み）｜pending（未達）｜unknown（ゲートのセクションがない — レガシー PDR）

フェーズ E：レポート

4 層を統合した進捗レポートを生成します。

## Product Roadmap Progress

### M01: Q2 User Auth — *Done means: production traffic on new auth, legacy login retired*
Tracker: github.com/org/repo/milestone/3 (native: 67% closed, due Sep 5)

| Item | Decision | Execution | Evidence | Status |
|------|----------|-----------|----------|--------|
| PDR-003: OAuth2 login | ✅ Completed | ✅ 3/3 closed (#142–#144) | ✅ src/auth/oauth/ verified | Live |
| PDR-004: SSO | ✅ Accepted | 🔄 2/4 closed (#186–#189) | ⚠️ no evidence section | In progress |
| PDR-005: Password reset | 🔄 Proposed | ⏳ 0/2 (#190, #191) | ❌ src/auth/reset/ missing | Not started |

| Gate | Type | Owner | Status |
|------|------|-------|--------|
| Security review passed | engineering | Sec team | ✅ green |
| Clinician sign-off | sign-off | Maya | ⏳ pending |
| 7-day cooling period | time | Lead | ⏳ pending (day 3/7) |

**Features**: 1/3 · **Issues**: 5/9 closed · **Gates**: 1/3 green · **Live**: No

⚠️ Done-means check: "production traffic on new auth" cannot be true while
2 items lack execution and 2 gates are pending.

完了条件に関する警告 — マイルストーンが「live」または「complete」と主張しているにもかかわらず、各層が green ではない場合：

条件	警告
すべての機能が Completed だが、未解決のイシューが残っている	"⚠️ Features claim complete but N issues still open — execution not finished"
すべてのイシューがクローズ済みだが、コードの証拠がない	"⚠️ Issues closed but code evidence missing — verify with /product-init"
すべての機能が完了しているが、保留中のゲートがある	"⚠️ Features done, milestone NOT live — N gates pending: [list]"
マイルストーンが Completed とマークされているが、ゲートのセクションがない	"⚠️ Milestone has no gates — consider adding acceptance criteria"

マイルストーン全体の概要：

## Overall Roadmap

| Milestone | Target | Features | Issues | Gates | Live |
|-----------|--------|----------|--------|-------|------|
| M01: Q2 User Auth | Sep 5 | 1/3 | 5/9 | 1/3 | No |
| M02: Q3 Enhancements | Oct 15 | 0/2 | 0/5 | 0/2 | No |

フェーズ F：ステータスの更新（任意）

ユーザーが明示的に更新をリクエストした場合に限ります（例：引数に「update」がある場合）。

各機能 PDR について：

• 関連するすべてのイシューがクローズ済みかつ証拠が検証済み → ステータスを Completed に更新します
• 未解決のイシューがある、または証拠がない → 更新をブロックし、次のように報告します："Cannot mark PDR-XXX as Completed: N issues open / evidence missing"
• オーバーライド：ユーザーが明示的に「force」と指定した場合 → 警告注記を付けて更新します

各マイルストーン PDR について：

• すべての機能が Completedかつすべてのゲートが green → ステータスを Completed に更新します
• それ以外の場合 → 更新をブロックし、保留中の項目／ゲートを報告します
• オーバーライド：ユーザーが明示的に「force」と指定した場合 → 警告付きで更新します

更新した PDR ファイルを書き込み、ステータス以外の内容はすべて保持します。

更新後は pdr.md インデックスを再生成します。

トラッカーの検出順序

イシューの状態を照会する際は、次の順序で利用可能なツールを検出します。

1. MCP ツール（優先）— 接続されている MCP サーバーを確認します。

   • GitHub：github_* ツールが利用可能
   • GitLab：gitlab_* ツールが利用可能
   • Jira：jira_* ツールが利用可能
   • Linear：linear_* ツールが利用可能

2. CLI によるフォールバック — そのトラッカーの MCP が利用できない場合：

   • GitHub：gh CLI
   • GitLab：glab CLI
   • Jira：jira CLI
   • Linear：linear CLI

3. アクセス手段なし — そのトラッカーの MCP も CLI も利用できない場合：

   • イシュー URL の状態を「不明」として報告します
   • 解決できないトラッカーごとに警告を 1 件出力します
   • 判定／証拠／ゲートの各層の処理は続行します

主なルール

4 層の誠実な評価

• マイルストーンが live となるのは、4 層すべて（判定 + 実行 + 証拠 + ゲート）が green の場合に限ります
• 1 層だけを根拠に「完了」と報告してはいけません
• 各層の状態が一致しない場合、完了条件に関する警告を必ず出します

イシュー参照

• PDR 内のイシュー URL は完全な URLである必要があります（ホスト名からトラッカーを判定します）
• ネイティブのトラッカーのマイルストーンリンクは任意ですが、推奨されます（ネイティブの進捗を取得します）
• イシュー参照がない場合 → 実行層を「トラッカーとの連携なし」として報告します

コードの検証

• モード A（明示的な Evidence）が推奨されます — PDR にはコードパスを記載した ### Evidence を含める必要があります
• モード B（ヒューリスティック）はフォールバックです — 信頼度が低いことをそのように報告します
• 詳細な再調査は roadmap ではなく init の役割です — 提案を添えて引き継ぎます

ステータスの更新

• --update は、保留中のイシュー／ゲート／証拠がある場合、明示的なオーバーライドがない限り更新をブロックします
• 更新するのは PDR のステータスのみで、PRD は直接更新しません — /product-implement が PRD を再生成します
• ステータスの更新時には、PDR のその他すべてのフィールドを保持します

後方互換性

• ### Gates がない PDR → ゲート層は「ゲートが宣言されていません」とし、追加するよう提案します
• ### Issues がない PDR → 実行層は「トラッカーとのリンクがありません」とします
• ### Evidence がない PDR → 証拠層はヒューリスティック（Mode B）になります
• レガシーのマイルストーンも引き続き動作します — 完了判定は機能のみとし、ゲートの採用を提案します

設定

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr
• PDR_MEMORY_DIR — {REPO_ROOT}/docs/adlc/memory/pdr（レガシーの .adlc/memory/pdr も読み取り互換性があり、件数は両方のルートの合計です）
• PRD_FILE — {REPO_ROOT}/docs/adlc/product/PRD.md
• MCP サーバー — GitHub、GitLab、Jira、Linear（自動検出）
• CLI ツール — gh、glab、jira、linear（フォールバック）

12-Factor との整合性

• Factor III（ミッションの定義）：完了の意味を正確に定義し、ミッションの進捗を追跡します
• Factor IX（検証優先）：コードの証拠とライブのトラッカー状態に照らして主張を検証します
• Factor XI（ディレクティブをコードとして扱う）：ゲートの状態は PDR ファイル内でバージョン管理されます

よくある合理化

合理化	実際のところ
「すべてのイシューがクローズされているので、完了です。」	イシューがクローズされても、コードが動作する証明にはなりません。証拠層が乖離を検出します。
「PDR を手動で Completed にすればいいだけです。」	ゲートがすべてグリーンでなければ、「Completed」は主張にすぎず、検証済みの状態ではありません。--update はこれをブロックします。
「イシュートラッキングは不要です。PDR のステータスで十分です。」	自己申告のステータスは実態と乖離します。実行状況の確かな根拠となるのは、ライブのトラッカー状態です。
「ロードマップからトラッカーにアクセスできないので、省略しましょう。」	機能低下への対応は組み込まれています。「状態不明」と報告し、ほかの層の処理を続けます。

危険信号

• ゲートが保留中のマイルストーンをライブにする — ゲートは基準であり、単なる提案ではありません。
• コードの証拠なしにイシューの状態を信頼する — イシューは早まってクローズされることがあります。確かな根拠となるのはコードです。
• 完了の意味の確認を省略する — 「コードの準備完了」≠「本番トラフィックの移行完了」です。この混同を防ぐために Done Means フィールドがあります。
• ロードマップ内で全面的なディスカバリーを実行する — 詳細な再ディスカバリーは init の役割です。ロードマップでは軽量なチェックを行い、次に引き継ぎます。

検証

• すべての PDR ファイルを読み込んだ（メモリー + 下書き）
• Features Included と Gates の表を持つマイルストーン PDR を特定した
• PDR からイシュー URL を抽出した
• MCP 経由でイシューの状態を照会した（または CLI にフォールバックした、あるいは不明として報告した）
• リンクがある場合、ネイティブトラッカーのマイルストーン進捗を取得した
• コードの証拠を検証した（Mode A は明示的、Mode B はヒューリスティック）
• マイルストーンごとにゲート状態を集約した
• 項目ごとのステータスを含む4層レポートを生成した
• 層間の不一致について、完了の意味に関する警告を出力した
• ロードマップ全体の概要表を生成した
• 保留中の層がある場合、--update を正しくブロックした（要求された場合）
• 更新後に pdr.md のインデックスを再生成した
• --update が明示的に要求されない限り、ファイルを一切変更していない