product-clarify

product-clarify

このスキルの機能

既存のPDRをレビューして品質上の不足を確認し、的を絞った確認質問を行い、承認されたPDRを Accepted ステータスにします。これはPRD生成前の品質ゲートです。

入力：.adlc/drafts/pdr/ にある個別の PDR-*.md ファイル（ステータスが Proposed または Discovered）

出力：更新された PDR-*.md ファイル（承認されたものはステータスが Accepted）、再生成された pdr.md インデックス

使用するタイミング

• /product-specify または /product-init の後、初期PDRを洗練させるとき
• /product-implement の前にPDRを承認するとき（必須 — implement は Accepted 以外をスキップします）
• マイルストーン前に定期的なPDRレビューを行うとき
• 機能領域を横断した分析で検出された不整合フラグを解決するとき

使用しないタイミング

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

実行手順

フェーズ 1：PDRの読み込み

1. セットアップスクリプトを実行：

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

2. {REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md のすべてのPDRファイルを読み込みます
3. {REPO_ROOT}/docs/adlc/memory/constitution.md から憲章を読み込みます。存在する場合は、レガシーの {REPO_ROOT}/.adlc/memory/constitution.md にフォールバックします（二重読み込み）。
4. インベントリを作成：

| PDR | Title | Status | Category |
|-----|-------|--------|----------|
| PDR-001 | Target Market | Proposed | Problem |
| PDR-002 | Primary Persona | Proposed | Persona |

ステップ 0：軽量ドラフト形式の検出

レビュー対象のドラフトが軽量ドラフトテンプレートを使用しているか確認します（フロントマターに type、evidence、source、revisit-when フィールドがあり、本文に正式テンプレートの全セクションではなく ## Rejected Alternatives ／ ## Reason セクションがあるかどうかで判別します）。

軽量形式の場合：

1. ドラフトに記録されたフィールド（Context、Decision、Rejected Alternatives、Reason）を読み込みます
2. 正式な完全版テンプレートに変換します：
   • ADR：Decision Drivers、Considered Options、Pros/Cons、Constitution Alignment、Related ADRs を含む完全なMADR形式
   • PDR：Market Forces、Consequences、Alternatives Considered、Links を含む完全なPDR形式
   • ChDR：Issue Links、Commits、Consequences、Evidence を含む完全なChDR形式
   • CDR：Context Type、Target Module、Descriptor、Evidence を含む完全なCDR形式
   • EVAL：Error Analysis、Pass/Fail Examples、Implementation Notes を含む完全な評価形式
3. セッションのコンテキストから情報を補い（軽量ドラフトで省略された可能性のある詳細を追加します）
4. 補完したドラフトをレビュー用に提示します

すでに完全な形式の場合は、通常のレビューに進みます。

フェーズ 2：PDRの品質分析

各PDRを基準に照らして確認します：

項目	確認内容	不足時の重大度
Context	問題が明確に記述されている	MEDIUM
Decision	実行可能で、検証可能である	HIGH
Consequences	肯定的な結果と否定的な結果の両方がある	HIGH
Success Metrics	目標値とともに定義されている	HIGH
Alternatives	中立的なトレードオフを含む案が少なくとも2つある	HIGH
Constitution	ビジョンと整合している	CRITICAL

品質チェックリスト：

• 問題／機会を説明する明確なコンテキスト
• 明示的で実行可能な意思決定の記述
• 肯定的な結果と否定的な結果の両方を記録
• 中立的なトレードオフを含む案が少なくとも2つある（「却下された理由」ではない）
• 成功指標が定義されている
• 軽減策とともにリスクが特定されている
• 有効なステータス値
• 他のPDRとの競合がない
• 憲章／ビジョンの原則との整合性

フェーズ 3：PDR間の整合性

1. 意思決定の競合：同じ概念について、PDRごとに異なる決定がされている
2. 依存関係の不足：相互に参照すべきPDRが参照していない
3. 用語の揺れ：同じ概念に異なる名称が使われている
4. 優先順位の競合：あるPDRではB2Bとされている一方、別のPDRではB2Cを前提としている

フェーズ 4：不足項目の特定

不足項目レポートを生成します：

## PDR Clarification Report

| PDR | Title | Gap Type | Severity |
|-----|-------|----------|----------|
| PDR-001 | [Title] | Missing alternatives | HIGH |
| PDR-002 | [Title] | Incomplete consequences | MEDIUM |

重大度：

• CRITICAL：憲章違反、意思決定の記述がない、成功指標がない
• HIGH：代替案がない、結果の記述が不足している
• MEDIUM：リスクが不完全、コンテキストが不明確
• LOW：軽微な表現上の問題

フェーズ 5：対話による詳細化

各不足点について、一度に1つずつ確認します。

## Clarification [N]: PDR-XXX — [Gap Type]

**Current State**:
[Quote current PDR content]

**Gap Identified**:
[Explain what's missing]

**Question**:
[Specific question]

**Suggested Options**:
| Option | Description |
|--------|-------------|
| A | [Option A] |
| B | [Option B] |
| C | [Custom response] |

ルール：

• 確認事項は一度に1つずつ提示します
• 深刻度の高いものから優先します — まずCRITICAL/HIGHから対応します
• 1回のセッションでの確認事項は最大5つです
• 重要でない確認事項は、ユーザーがスキップできるようにします
• 回答のたびに変更点を要約します

フェーズ 6：Constitution の違反（該当する場合）

重複の場合：

## Constitution Duplication Detected

**PDR**: PDR-XXX — [Title]
**Constitution Principle**: §[Section] — [Principle]

**Options**:
| Option | Action |
|--------|--------|
| A | Remove PDR |
| B | Convert to Reference |
| C | Add Context |
| D | Extend |

違反の場合（⭐ 推奨：Constitution を修正）：

## Constitution Violation Detected ⭐

**⭐ RECOMMENDED: A. Amend Constitution**
Update constitution §[Section] to accommodate this decision.

**Alternatives**:
B. Override in PDR — Document justification
C. Revise PDR — Change decision to comply
D. Remove PDR — Delete and follow constitution

フェーズ 7：PDR ファイルを更新する

1. ファイルごとに確認事項を反映します
2. 該当する場合はステータスを更新します
3. 「Last Updated」のタイムスタンプを更新します
4. pdr/pdr.md インデックスを再生成します — pdr-lib.sh の generate_pdr_index drafts を呼び出します（または pdr-lib.ps1 の Generate-PdrIndex drafts）。これは frontmatter 優先、見出しフォールバックのパーサーを使用し、H2 と H3 の両方のメタデータを処理して空行の不具合を防ぎます。

フェーズ 8：PDR の承認 ⭐

重要：/product-implement が処理するのは、ステータスがAcceptedのPDRのみです。

## PDR Approval ⭐

**Total PDRs**: [N]
**Status Distribution**:
- Accepted: [N]
- Proposed: [N]
- Discovered: [N]

**Options**:
| Option | Action |
|--------|--------|
| A | Accept All — Change Proposed/Discovered → Accepted |
| B | Review Specific — Select individual PDRs |
| C | Defer — Keep current status |

一括承認（オプション A）：

## Confirm Bulk Approval

Change [N] PDRs to Accepted?

| PDR | Current | New |
|-----|---------|-----|
| PDR-001 | Proposed | Accepted |
| PDR-002 | Discovered | Accepted |

承認後：

## PDRs Approved

**Ready for Implementation**:
- Accepted PDRs: [N]
- Pending: [N]

Run `/product-implement` to generate PRD.md.

主なルール

既存内容を損なわない詳細化

• ユーザーの明示的な承認なしに、既存のPDRを削除しないでください
• 文言を更新する際は、元の意図を維持します
• 影響と代替案は置き換えずに追加します
• 更新したタイムスタンプで変更を記録します

焦点を絞った確認

• 一度に1つずつ質問します
• 具体的で回答可能な質問にします
• 可能な場合は選択肢を提案します
• ユーザーの時間を尊重します

Constitution の権限

• Constitution の違反には必ずフラグを立てます
• 正当な理由なしに、PDR が MUST 原則に優先することはできません
• 対立が構造的なものである場合は、Constitution の更新を提案します

設定

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr
• PDR_INDEX — {REPO_ROOT}/.adlc/drafts/pdr/pdr.md
• CONSTITUTION — {REPO_ROOT}/docs/adlc/memory/constitution.md（旧 .adlc/memory/constitution.md をフォールバックとして使用）

12-Factor との整合性

• Factor III（ミッションの定義）：実行前にプロダクトのミッションが明確に定義されていることを確認します
• Factor VII（品質ゲート）：自動生成の前に、人の判断を適用します

よくある誤った正当化

誤った正当化	実際
「PDR に問題はなさそうだから、確認は省こう。」	ステータスが Accepted でないPDRは実装時にスキップされ、PRD から決定事項が黙って抜け落ちます。
「まとめて全部承認すればいい。」	レビューなしの一括承認は、問題のある決定を PRD に埋め込むリスクがあります。
「Constitution に警告を出しておけば、基本的には問題ない。」	Constitution の違反は、プロダクトの一貫性を損なうためCRITICALです。

注意すべき兆候

• 承認手順を省略する — Accepted のステータスがないと、実装時にPDRは無視されます。
• 内容を読まずに承認する — 品質ゲートの目的が損なわれます。
• PDR 間の矛盾を指摘しない — 一貫性のないPDRは、まとまりのない PRD を生みます。

検証

• すべてのPDRファイルを読み、一覧化した
• 各PDRに品質チェックリストを適用した
• PDR 間の一貫性を検証した
• Constitution との整合性を確認した
• 不足点を特定し、優先順位を付けた
• ファイルごとに確認事項を反映した
• pdr.md インデックスを再生成した
• 承認フェーズを完了した（Accept/Review/Defer）
• 承認済みのPDRのファイル内のステータスが「Accepted」になっている
• 重複または欠落しているPDR IDがない