fix(suggest)

dev-reports/issue/167/issue-review/hypothesis-verification.md

@@ -0,0 +1,35 @@
+# 仮説検証レポート: Issue #167
+
+## 検証対象の仮説
+
+suggestコマンドがナレッジグラフからIssue関連の全ファイルを1件ずつcontextコマンドに展開するため、提案数が80件に膨らむ。
+
+## 検証結果: **Confirmed**
+
+### 根拠
+
+1. **フィルタリングなしの展開**: `query_knowledge_graph()` (suggest.rs:221-246) がIssueに紐づく全ドキュメントを返却
+2. **リレーション種別フィルタなし**: has_progress, modifies を含む全リレーションが展開対象
+3. **doc_subtypeフィルタなし**: JSON成果物、stage別レビュー等も個別展開
+4. **件数制限なし**: `prepend_knowledge_steps()` (suggest.rs:249-276) が全ドキュメントを1件1コマンドで展開
+
+### 参照: before_changeコマンドの既存実装
+
+`before_change.rs` では以下の制御が既に実装済み:
+- `relation_priority()` による優先度付け (has_design=0, has_workplan=1, has_review=2, has_progress=3, modifies=4)
+- `MAX_DOCS_PER_ISSUE = 2` によるIssue単位の件数制限
+- `modifies` リレーションの除外フィルタ
+
+### 改善案の妥当性
+
+Issue記載の改善案（ドキュメント種別で優先度をつけてフィルタリング）は、既存の `before_change.rs` の実装パターンと整合しており、妥当。
+
+### 関連コード
+
+| コンポーネント | ファイル | 行 | 関数 |
+|---|---|---|---|
+| KG展開（問題箇所） | suggest.rs | 249-276 | `prepend_knowledge_steps()` |
+| KGクエリ | suggest.rs | 221-246 | `query_knowledge_graph()` |
+| リレーション定義 | knowledge.rs | 80-88 | `KnowledgeRelation` |
+| 参照実装 | before_change.rs | 331-340 | `relation_priority()` |
+| 参照実装 | before_change.rs | 349-381 | Issue単位グルーピング |

dev-reports/issue/167/issue-review/original-issue.json

@@ -0,0 +1 @@
+{"body":"## 概要\n\n#157 の修正でsuggestがナレッジグラフを参照するようになったが、Issue関連の全ファイルを1件ずつ`context`コマンドに展開するため、提案数が80件に膨らみ実用的でない。\n\n## 再現手順\n\n```bash\ncommandindexdev suggest --for \"Issue #299のiPadレイアウト修正の設計判断を理解したい\"\n```\n\n### 実際の結果\n\n80件の提案。Issue #299の全関連ファイル（JSON成果物、stage別レビューコンテキスト等を含む）が個別にcontext展開される:\n\n```\n1. commandindexdev issue 299 --format json (OK - これは適切)\n2. commandindexdev context -- 'dev-reports/design/issue-299-...' --max-files 5\n3. commandindexdev context -- 'dev-reports/issue/299/pm-auto-dev/...' --max-files 5\n...\n58. commandindexdev context -- 'tests/unit/config/z-index.test.ts' --max-files 5\n...（計75件のIssue関連context + 5件のBM25ベース提案）\n```\n\n### 期待される結果\n\n5-10件程度の提案。代表文書に絞る:\n\n```\n1. commandindexdev issue 299 --format json\n2. commandindexdev context -- 'dev-reports/design/issue-299-ipad-layout-fix-design-policy.md' --max-files 5\n3. commandindexdev context -- 'dev-reports/issue/299/work-plan.md' --max-files 5\n4. commandindexdev context -- 'dev-reports/issue/299/issue-review/summary-report.md' --max-files 5\n5. commandindexdev context -- 'dev-reports/issue/299/multi-stage-design-review/summary-report.md' --max-files 5\n```\n\n## 改善案\n\nナレッジグラフからの展開時にドキュメント種別で優先度をつけてフィルタリングする:\n\n1. **最優先（常に含める）**: `has_design`（設計ポリシー）、`has_workplan`（作業計画）\n2. **次点（サマリーのみ）**: `has_review`のうちsummary-report.mdのみ。stage別の個別レビューは省略\n3. **省略**: JSON成果物（`*-context.json`, `*-result.json`）、`has_progress`\n4. **省略**: `modifies`のソースコード個別展開\n\nsuggestの目的は「どこから調べ始めるか」のガイドであり、全文書の網羅ではない。\n\n## テスト環境\n\n- commandindex 0.1.0\n- CommandMateリポジトリ（2910ファイル、124690セクション）","title":"suggestコマンドのナレッジグラフ展開が過剰（80件提案）"}

dev-reports/issue/167/issue-review/stage1-review-context.json

@@ -0,0 +1,57 @@
+{
+  "must_fix": [
+    {
+      "id": "MF-1",
+      "title": "改善案の「省略: modifiesのソースコード個別展開」はsuggestでは不要な記述",
+      "description": "Issue本文の改善案4番目に「省略: modifiesのソースコード個別展開」とあるが、suggest.rsのprepend_knowledge_steps()はfind_knowledge_by_issue()の結果をそのまま使っており、find_knowledge_by_issue()はdocumentノードとfileノードの両方を返す（kn_doc.type IN ('document', 'file')）。つまりmodifies関係のfileノード（ソースコード）もcontext展開される。before_change.rsではdocs.retain(|d| d.relation != KnowledgeRelation::Modifies)で明示的に除外しているが、suggest.rsにはこのフィルタがない。Issue本文はこの問題を正しく指摘しているが、「省略」ではなく「フィルタリングで除外」と明示すべき。",
+      "suggestion": "改善案を以下のように修正: modifiesのfileノードはprepend_knowledge_steps()の前段でretain()により明示的に除外する。before_change.rs L434のパターンを参考にすること。受け入れ基準にも「modifies関係のファイルノードがsuggestの提案に含まれないこと」を明記する。"
+    },
+    {
+      "id": "MF-2",
+      "title": "受け入れ基準が未定義",
+      "description": "Issue本文に受け入れ基準（Acceptance Criteria）が記載されていない。改善案は方向性を示しているが、具体的な合格条件（提案数の上限、フィルタリング対象の網羅的リスト、既存テストへの影響など）が不明確。",
+      "suggestion": "以下の受け入れ基準を追加すべき: (1) ナレッジグラフから展開されるcontextステップ数がIssueあたり最大N件に制限されること、(2) has_progress関係のドキュメントが除外されること、(3) modifies関係のファイルノードが除外されること、(4) has_reviewのうちsummary-report.md以外のstage別レビューが除外されること、(5) JSON成果物（.json拡張子）が除外されること、(6) 既存テストが更新され新しいフィルタリングロジックをカバーすること。"
+    }
+  ],
+  "should_fix": [
+    {
+      "id": "SF-1",
+      "title": "before_change.rsのgroup_and_limit_by_issueパターンをsuggestでも採用すべきことをIssueに明記する",
+      "description": "before_change.rsにはgroup_and_limit_by_issue()という成熟したパターンがあり、Issue単位のグルーピング、relation_priorityによるドキュメント選択、MAX_DOCS_PER_ISSUE制限を実現している。Issue本文の改善案はフィルタリングの方向性を示しているが、この既存パターンの再利用を明示的に推奨していない。",
+      "suggestion": "改善案に「before_change.rsのgroup_and_limit_by_issue()およびrelation_priority()パターンを参考に、suggest用のフィルタリング関数を実装する」と明記する。"
+    },
+    {
+      "id": "SF-2",
+      "title": "フィルタリングのレイヤー設計を明確にする",
+      "description": "フィルタリングを(A) find_knowledge_by_issue()のSQL側で行うか、(B) prepend_knowledge_steps()の前段で行うか、(C) prepend_knowledge_steps()内部で行うかが不明確。before_change.rsは(B)のパターンを採用している。",
+      "suggestion": "before_change.rsと一貫性を保つため、(B)のパターンを推奨する。find_knowledge_by_issue()のSQL変更は不要（他のコマンドへの影響を避ける）。"
+    },
+    {
+      "id": "SF-3",
+      "title": "KnowledgeDocResultにdoc_subtypeフィールドがない問題",
+      "description": "改善案ではhas_reviewのうちsummary-report.mdのみを残すフィルタリングを提案しているが、KnowledgeDocResult構造体にはdoc_subtypeフィールドがない。そのためsummary-report.mdの判別はfile_pathの文字列マッチに依存することになるが、Issue本文ではこの制約に言及していない。",
+      "suggestion": "file_pathの文字列パターンマッチで「summary-report.md」を含むかどうかで判定する簡易アプローチで十分。Issueに選択の根拠を記載すべき。"
+    },
+    {
+      "id": "SF-4",
+      "title": "提案数の具体的上限値をIssueに記載する",
+      "description": "Issue本文で「5-10件程度の提案」と期待されるが、具体的な上限定数が示されていない。",
+      "suggestion": "MAX_KG_DOCS_PER_ISSUE = 2 を定義。最大ステップ数 = MAX_ISSUE_NUMBERS(3) * (1 + MAX_KG_DOCS_PER_ISSUE(2)) = 9ステップ + 既存戦略ステップ。"
+    }
+  ],
+  "nice_to_have": [
+    {
+      "id": "NH-1",
+      "title": "issueコマンドステップとcontextステップの重複可能性",
+      "description": "issueコマンド自体がドキュメント一覧を返すため、contextで個別展開するのは情報の重複がある。",
+      "suggestion": "フィルタリング実装後、issueコマンドステップを残すかどうかを検討する。"
+    },
+    {
+      "id": "NH-2",
+      "title": "JSON成果物の除外ルールをパターンルールと整合させる",
+      "description": "knowledge.rsのparse_dev_report_path()は既にJSONファイルをパターンマッチ対象外としている。ナレッジグラフに登録されるドキュメントノードにJSONファイルは含まれない。ただしfileノード（modifies関係）経由でJSONファイルが含まれる可能性はある。",
+      "suggestion": "Issue本文の改善案から「JSON成果物の省略」を削除するか、「modifiesのfileノード除外によりJSON成果物も自動的に除外される」と補足する。"
+    }
+  ],
+  "summary": "Issue #167の問題指摘は正確。before_change.rsに参考にすべき成熟したパターンが存在する。修正必須事項は(1) modifiesのfileノード除外の明示、(2) 受け入れ基準の定義。改善事項として、既存パターン再利用の明示、フィルタリングレイヤーの設計方針、doc_subtypeがない制約への対処方針、具体的な上限定数の定義がある。"
+}

dev-reports/issue/167/issue-review/stage2-apply-result.json

@@ -0,0 +1,15 @@
+{
+  "stage": 2,
+  "action": "apply_review",
+  "applied_items": ["MF-1", "MF-2", "SF-1", "SF-2", "SF-3", "SF-4", "NH-1", "NH-2"],
+  "changes": [
+    "modifies除外をretain()によるフィルタリングと明示",
+    "受け入れ基準セクションを新設（7項目）",
+    "before_change.rsのパターン再利用を明記",
+    "フィルタリングレイヤーの処理フロー図を追加",
+    "file_pathパターンマッチによるhas_reviewフィルタを注記",
+    "MAX_KG_DOCS_PER_ISSUE = 2 を定数として明記",
+    "補足セクションにNH-1, NH-2を追記"
+  ],
+  "issue_updated": true
+}

dev-reports/issue/167/issue-review/stage3-review-context.json

@@ -0,0 +1,63 @@
+{
+  "must_fix": [
+    {
+      "id": "MF-1",
+      "title": "KnowledgeDocResultにdoc_subtypeフィールドがなく、has_reviewのサブタイプ判別不可",
+      "description": "KnowledgeDocResult (symbol_store.rs:66-71) にdoc_subtypeフィールドがないため、IssueReview/DesignReview(summary)とStageReview(非summary)を区別できない。find_knowledge_by_issue()もmetadata/doc_subtypeを取得していない。",
+      "suggestion": "file_pathパターンマッチ（summary-report.mdで終わるかどうか）で判定する。doc_subtypeのスキーマ変更は不要。"
+    },
+    {
+      "id": "MF-2",
+      "title": "新しいフィルタリングロジックのユニットテストが必要",
+      "description": "既存のprepend_knowledge_stepsテストはフィルタリング前の挿入ロジックのみテスト。新しいフィルタリングロジック（modifies除外、has_progress除外、has_review非summary除外、Issue単位制限）のテストがない。",
+      "suggestion": "filter_and_limit_kg_docs()のユニットテストを追加: (1) modifies除外、(2) has_progress除外、(3) has_review非summary除外、(4) has_design/has_workplan保持、(5) MAX_KG_DOCS_PER_ISSUE制限、(6) 全件フィルタ後0件のエッジケース。"
+    }
+  ],
+  "should_fix": [
+    {
+      "id": "SF-1",
+      "title": "has_reviewフィルタリング基準の明確化",
+      "description": "has_reviewにはIssueReview(summary-report.md), DesignReview(summary-report.md), StageReview(stage別ファイル)が含まれる。ALLを除外するのかsummary以外を除外するのかを明確にすべき。",
+      "suggestion": "file_pathがsummary-report.mdで終わるhas_reviewのみ保持、それ以外を除外する方針。"
+    },
+    {
+      "id": "SF-2",
+      "title": "Issue単位グルーピングでrelation_priorityソートを実装すべき",
+      "description": "before_change.rsと同じパターンで、Issue単位グルーピング後にrelation_priorityでソートし上位を選択すべき。",
+      "suggestion": "KnowledgeRelation enumにpriority()メソッドを追加するか、suggest.rs内でrelation_priority関数を定義する。"
+    },
+    {
+      "id": "SF-3",
+      "title": "before_change.rsのgroup_and_limit_by_issueはBeforeChangeFinding型で直接再利用不可",
+      "description": "before_change.rsの関数はBeforeChangeFinding型を扱う。suggest.rsではKnowledgeDocResultを扱うため、専用のフィルタリング関数が必要。",
+      "suggestion": "suggest.rs内にfilter_and_limit_kg_docs()関数を実装する。KnowledgeRelation enumで直接パターンマッチ。"
+    }
+  ],
+  "nice_to_have": [
+    {
+      "id": "NH-1",
+      "title": "relation_priorityを共通モジュールに抽出",
+      "description": "before_change.rsとsuggest.rsで同じ優先度ロジックが必要。KnowledgeRelation enumにpriority()メソッドを追加すればDRY。",
+      "suggestion": "KnowledgeRelation::priority() -> u8 メソッド追加。"
+    },
+    {
+      "id": "NH-2",
+      "title": "MAX_KG_DOCS_PER_ISSUEをbefore_changeと共有検討",
+      "description": "before_change.rsのMAX_DOCS_PER_ISSUE=2と同値。将来的に共有定数にする検討。",
+      "suggestion": "現時点ではsuggest.rs内に定義。将来的に共通化。"
+    },
+    {
+      "id": "NH-3",
+      "title": "他コマンドへの影響なし（確認済み）",
+      "description": "変更はsuggest.rsのquery_knowledge_graph()とprepend_knowledge_steps()の間のみ。before_change, issue等の他コマンドへの副作用なし。",
+      "suggestion": "対応不要。"
+    },
+    {
+      "id": "NH-4",
+      "title": "パフォーマンス影響は無視可能",
+      "description": "O(n) retain() + O(n) groupingのみ。BM25/semantic検索やSQLiteクエリに比べて無視可能。",
+      "suggestion": "対応不要。"
+    }
+  ],
+  "summary": "主要リスクはMF-1: KnowledgeDocResultにdoc_subtypeがなく、has_reviewのsummary判別にfile_pathパターンマッチが必要。MF-2: フィルタリングロジックのテスト追加が必要。変更はsuggest.rsに限定され他コマンドへの影響なし。パフォーマンス影響も無視可能。"
+}

dev-reports/issue/167/issue-review/stage4-apply-result.json

@@ -0,0 +1,15 @@
+{
+  "stage": 4,
+  "action": "apply_impact_review",
+  "applied_items": ["MF-1", "MF-2", "SF-1", "SF-2", "SF-3", "NH-1", "NH-3"],
+  "changes": [
+    "file_path.ends_with(\"summary-report.md\")による判定方針を明記",
+    "テスト要件セクション新設（5つのユニットテスト項目）",
+    "has_reviewフィルタリング基準の明確化",
+    "relation_priorityソート順を明記",
+    "filter_and_limit_kg_docs()関数新設の方針を追加",
+    "relation_priority共通化検討を補足セクションに追加",
+    "他コマンドへの影響なし確認を記載"
+  ],
+  "issue_updated": true
+}