product-analyze

product-analyze

このスキルでできること

読み取り専用で、プロダクトの一貫性を分析します。

1. PDR の品質 — 完全性、明確さ、標準への準拠
2. PDR→PRD の乖離 — PRD に反映されていない決定事項
3. PRD→PDR の乖離 — 裏付けとなる PDR がない PRD の要素
4. PDR 間の一貫性 — PDR 間の矛盾
5. 陳腐化 — 古い参照、プレースホルダー、参照されたままの非推奨 PDR
6. Mermaid の構文 — 場所と推奨パッチを示して無効な図のブロックを報告します（Mermaid 検出パス）

出力：構造化された Markdown 分析レポート（ファイルは変更されません）

使用するタイミング

• /product-implement の後に、生成された PRD を検証するとき
• /product-clarify の後に、改良内容を確認するとき
• 機能開発の前に、プロダクトが確かな状態であることを確認するとき
• プロダクトの進化に伴う乖離を検出するため、定期的に実行するとき

使用しないタイミング

• プロダクトの成果物が存在しない場合（先に /product-init または /product-specify を使用してください）
• ファイルを変更したい場合（このスキルは分析専用です）

実行手順

フェーズ 1：成果物の読み込み

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

読み込むファイル：

• docs/adlc/product/PRD.md（レガシーのリポジトリルートにある PRD.md をフォールバックとして使用 — 両方を読み込みます）
• {REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md（個々の PDR ファイル）
• {REPO_ROOT}/docs/adlc/memory/constitution.md。存在する場合は、レガシーの {REPO_ROOT}/.adlc/memory/constitution.md にフォールバックします（両方を読み込みます）

インベントリを作成：

| Artifact | Path | Status |
|----------|------|--------|
| Product PRD | docs/adlc/product/PRD.md (legacy PRD.md fallback) | Found/Missing |
| Product PDRs | .adlc/drafts/pdr/ | [N] files |
| Constitution | docs/adlc/memory/constitution.md (legacy .adlc/memory fallback) | Found/Missing |

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

各 PDR ファイルについて、以下を確認します。

項目	確認内容	重大度
コンテキスト	問題が明確に記述されている	MEDIUM
決定事項	実行可能で、テスト可能である	HIGH
結果	肯定的な結果と否定的な結果の両方が記載されている	HIGH
成功指標	目標値とともに定義されている	HIGH
代替案	中立的なトレードオフを示す代替案が少なくとも 2 つある	HIGH
憲章	ビジョンに沿っている	CRITICAL

フェーズ 3：PDR 間の一貫性

1. 決定事項の矛盾：互いに矛盾する PDR（例：B2B 対 B2C）
2. 依存関係の欠落：相互に参照すべき PDR
3. 用語の不一致：同じ概念に異なる名称が付けられている
4. 戦略の一貫性：問題、ペルソナ、指標の整合性

フェーズ 4：PDR→PRD の乖離（順方向の同期）

各 PDR について、決定事項が PRD に記載されているか確認します。

PDR の要素	PRD での想定箇所	セクション
問題に関する決定事項	問題の記述	3
ペルソナに関する決定事項	ペルソナ	6
スコープに関する決定事項	要件／対象外	7 / 9
指標に関する決定事項	成功指標	5
ビジネスモデル	概要	2
NFR に関する決定事項	非機能要件	8

フェーズ 5：PRD→PDR の乖離（逆方向の同期）

1. PDR のない要件：スコープの根拠がないユーザーストーリー
2. PDR のないペルソナ：対応するペルソナ PDR がないペルソナ
3. PDR のない指標：対応する指標 PDR がない成功指標
4. PDR のないリスク：結果の記録がないリスク

フェーズ 6：陳腐化の検出

1. 参照されたままの非推奨 PDR：PRD がステータス「Deprecated」の PDR を参照している
2. プレースホルダー：[TODO]、[TBD]、[PRODUCT_NAME]、[DATE]
3. 日付の不整合：PDR の日付が PRD の最終更新日より古い
4. 孤立した参照：PDR ID が記載されているが、対応するファイルが存在しない

フェーズ 7：Mermaid 構文の検証（Mermaid 検出パス）

目的：PRD 内の無効な Mermaid ブロックを、場所と推奨パッチとともに報告し、壊れた図が見過ごされたまま公開されることを防ぎます。

共有バリデーターを実行します — ルールセットはバリデーターが管理します（標準ルールは architect-clarify にあり、ルールはバリデーター自体に一度だけ記載されています）。ここでしきい値を再導出したり、再記述したりしないでください。

sh: {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/mermaid-lint.sh --tsv <artifact>

architect-clarify スキルが必要です（adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify）。終了コード：0 は問題なし、1 は HIGH（構文エラー）が存在、2 は MEDIUM（スタイル）の指摘のみです。

ルールの用語 — バリデーター独自の ID を使用します。各指摘には重大度が付随し、ここで推測することはありません。

ルール	意味
M001-fence-not-closed	```mermaid ブロックが閉じられていません
M002-unknown-diagram-type	タイプのキーワードが既知のセットに含まれていません。確認が必要ですが、誤って HIGH と判定することはありません
M003-missing-diagram-type	ブロックに図のタイプがまったく宣言されていません
M004-empty-block	ブロックに図の内容がありません。コメントとディレクティブは内容として数えません
M005-empty-body	タイプは宣言されていますが、その後にステートメントがありません。Mermaid はこれを描画する（空のチャート）ため、構文エラーではなく MEDIUM のスタイル上の指摘です。指摘箇所はタイプ宣言です
M006-malformed-gantt-header	gantt ブロックの最初のステートメント（コメントとディレクティブはスキップ）が、gantt キーでもタスク行でもありません。形式不正な最初のステートメントは構文エラー（HIGH）です。タスク行の形式に一致するステートメントは、最大でも MEDIUM であり、誤って HIGH と判定することはありません
M007-malformed-sequence-diagram	sequenceDiagram の最初のステートメント（コメントとディレクティブはスキップ）が、ドキュメント化されたシーケンスステートメントではありません。該当するのは participant、メッセージ、または title、autonumber、box、critical、break などのキーワードです。これらのいずれにも一致しないステートメントは構文エラー（HIGH）です
M008-malformed-entity-diagram	erDiagram の最初のステートメント（コメントとディレクティブはスキップ）に、Mermaid のエンティティ名文法で受け入れられない文字が含まれています。リレーション、属性ブロック、または文字、数字、_、-、.、スペースで構成された単独の名前は有効です（Mermaid は単独の名前を独立したエンティティとして解析します）。解析できない名前のみが構文エラー（HIGH）です
M009-non-mandated-keyword	プロダクトの要件で flowchart が必須となっている箇所で graph が使用されています

ルール：

• PRD と、図を含むすべてのプロダクト成果物に対して実行します。
• 指摘内容はそのままレポートに反映します。重大度、場所、推奨パッチはバリデーターが提示するものを使用し、言い換えたり、重大度を変更したりしないでください。
• このパスは読み取り専用です（ライフサイクルの書き込み範囲）。修正は /product-implement または人間が行い、このスキルでは行いません。
• 認識されない図のタイプは MEDIUM であり、HIGH ではありません。ルールセットは構文エラーを誤って報告してはなりません。
• タイプが宣言されていてステートメントがまったくない場合でも、描画されます（空のチャート）。バリデーターはこれを MEDIUM（M005-empty-body）として、タイプ宣言箇所に報告します。構文エラーではありません。HIGH となるのは、最初のステートメントが形式不正な場合に限ります。
• Mermaid のコメント（%% …）やディレクティブ（%%{ … }%%）は内容ではありません。バリデーターは、ブロックのタイプまたは最初のステートメントを読み取る際、これらをスキップするため、コメントから始まる図も有効です。

フェーズ 8：重大度の割り当て

重大度	基準
CRITICAL	憲章への違反、主要な要件が文書化されていない
HIGH	要件に影響する PDR→PRD の乖離、PDR 間の矛盾
MEDIUM	影響の記述不足、情報の古さ、用語の不統一
LOW	スタイルの改善、軽微なドキュメントの不足

フェーズ 9：レポートの生成

## Product Analysis Report

### Analysis Summary
| Attribute | Value |
|-----------|-------|
| Mode | [Full/PDRs/Sections] |
| Files Analyzed | [List] |
| Analysis Date | [Current date] |

### Findings
| ID | Pass | Severity | Location | Summary | Recommendation |
|----|------|----------|----------|---------|----------------|
| A1 | PDR Quality | MEDIUM | PDR-003 | Missing success metrics | Add metrics section |
| B1 | Inter-PDR | HIGH | PDR-002, PDR-005 | Conflicting target markets | Resolve B2B vs B2C |
| C1 | PDR→PRD | HIGH | PRD:5 | Persona not in PRD | Update PRD section 5 |
| D1 | PRD→PDR | HIGH | PRD:6 | Feature has no PDR | Create PDR |
| F1 | Staleness | LOW | PRD:1 | [PRODUCT_NAME] placeholder | Fill product name |
| G1 | Mermaid Syntax | HIGH | PRD:42 (fence #3) | ` ```mermaid ` block has no content | add the diagram body, e.g. `flowchart TD / A[Start] --> B[End]` |

### Coverage Metrics
| Metric | Value |
|--------|-------|
| PDR Count | [N] |
| PRD Sections Complete | [N]/12 |
| PDR→PRD Coverage | [N]% |
| PRD→PDR Coverage | [N]% |

### Issue Distribution
| Severity | Count |
|----------|-------|
| CRITICAL | [N] |
| HIGH | [N] |
| MEDIUM | [N] |
| LOW | [N] |

### Next Actions
- **CRITICAL issues**: Resolve constitution violations before proceeding
  - Command: `/product-clarify`
- **HIGH PDR quality**: Address missing alternatives and consequences
  - Command: `/product-clarify`
- **PDR→PRD drift**: Update PRD to reflect PDR decisions
  - Command: `/product-implement --update`
- **PRD→PDR drift**: Create missing PDRs
  - Command: `/product-specify` or `/product-init`

主なルール

分析の完全性

• ファイルを変更しないでください — 読み取り専用です
• 不足している内容を捏造しないでください — 不在の内容は正確に報告してください
• 憲章違反を優先してください — 常に CRITICAL としてください
• 根拠に基づく所見を提示してください — 具体的な場所を引用してください
• Mermaid の検査では何も書き込みません — 報告のみを行います。修正は /product-implement または人間が行います（ライフサイクルの書き込み範囲）

報告基準

• 所見は最大 50 件にしてください — 超過分は要約にまとめてください
• 場所を記載してください — 必ずファイルまたはセクションを示してください
• 実行可能な推奨事項を提示してください — 各所見に修正案を付けてください
• カバレッジ指標を算出してください — 完全性を定量化してください

設定

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr
• PRD_FILE — {REPO_ROOT}/docs/adlc/product/PRD.md
• CONSTITUTION — {REPO_ROOT}/docs/adlc/memory/constitution.md（レガシーの .adlc/memory/constitution.md をフォールバックとして使用）
• MERMAID_LINTER — {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/mermaid-lint.sh（architect-clarify の正規の場所です。このスキルがインストールされている必要があります）

12-Factor との整合性

• Factor IX（検証優先）：後続作業の前に成果物を検証します
• Factor XI（ディレクティブをコードとして管理）：バージョン管理されたディレクティブの品質を確認します

検証

• すべての成果物を読み込み、一覧化した
• 各ファイルに PDR 品質チェックリストを適用した
• PDR 間の整合性を確認した
• 双方向のドリフト検出を完了した
• 陳腐化のスキャンを実施した
• Mermaid の構文を検証した（共通リンターを実行し、壊れたブロックすべてに重要度、場所、パッチを記載した）
• 重要度を正しく設定した
• 所見の表を含む形式でレポートを作成した
• カバレッジ指標を算出した
• コマンドを含め、次のアクションを推奨した
• ファイルを一切変更していない