create-ai-project 1.13.0 → 1.14.0

package/.claude/commands-en/reverse-engineer.md

@@ -0,0 +1,301 @@
+---
+name: reverse-engineer
+description: Generate PRD and Design Docs from existing codebase through discovery, generation, verification, and review workflow
+---
+
+**Command Context**: Reverse engineering workflow to create documentation from existing code
+
+Target: $ARGUMENTS
+
+**TodoWrite**: Register phases first, then steps within each phase as you enter it.
+
+## Step 0: Initial Configuration
+
+### 0.1 Scope Confirmation
+
+Use AskUserQuestion to confirm:
+1. **Target path**: Which directory/module to document
+2. **Depth**: PRD only, or PRD + Design Docs
+3. **Reference Architecture**: layered / mvc / clean / hexagonal / none
+4. **Human review**: Yes (recommended) / No (fully autonomous)
+
+### 0.2 Output Configuration
+
+- PRD output: `docs/prd/` or existing PRD directory
+- Design Doc output: `docs/design/` or existing design directory
+- Verify directories exist, create if needed
+
+## Workflow Overview
+
+```
+Phase 1: PRD Generation
+  Step 1: Scope Discovery (all units)
+  Step 2-5: Per-unit loop (Generation → Verification → Review → Revision)
+
+Phase 2: Design Doc Generation (if requested)
+  Step 6: Scope Discovery (all components per PRD)
+  Step 7-10: Per-component loop (Generation → Verification → Review → Revision)
+```
+
+**Context Passing**: Pass structured JSON output between steps. Use `$STEP_N_OUTPUT` placeholder notation.
+
+## Phase 1: PRD Generation
+
+**Register in TodoWrite**:
+- Step 1: PRD Scope Discovery
+- Per-unit processing (Steps 2-5 for each unit)
+
+### Step 1: PRD Scope Discovery
+
+**Task invocation**:
+```
+subagent_type: scope-discoverer
+prompt: |
+  Discover PRD targets in the codebase.
+
+  scope_type: prd
+  target_path: $USER_TARGET_PATH
+  reference_architecture: $USER_RA_CHOICE
+  focus_area: $USER_FOCUS_AREA (if specified)
+```
+
+**Store output as**: `$STEP_1_OUTPUT`
+
+**Quality Gate**:
+- At least one PRD unit discovered → proceed
+- No units discovered → ask user for hints
+
+**Human Review Point** (if enabled): Present discovered units for confirmation.
+
+### Step 2-5: Per-Unit Processing
+
+**Complete Steps 2→3→4→5 for each unit before proceeding to the next unit.**
+
+#### Step 2: PRD Generation
+
+**Task invocation**:
+```
+subagent_type: prd-creator
+prompt: |
+  Create reverse-engineered PRD for the following feature.
+
+  Operation Mode: reverse-engineer
+  External Scope Provided: true
+
+  Feature: $UNIT_NAME (from $STEP_1_OUTPUT)
+  Description: $UNIT_DESCRIPTION
+  Related Files: $UNIT_RELATED_FILES
+  Entry Points: $UNIT_ENTRY_POINTS
+
+  Skip independent scope discovery. Use provided scope data.
+  Create final version PRD based on code investigation within specified scope.
+```
+
+**Store output as**: `$STEP_2_OUTPUT` (PRD path)
+
+#### Step 3: Code Verification
+
+**Task invocation**:
+```
+subagent_type: code-verifier
+prompt: |
+  Verify consistency between PRD and code implementation.
+
+  doc_type: prd
+  document_path: $STEP_2_OUTPUT
+  code_paths: $UNIT_RELATED_FILES (from $STEP_1_OUTPUT)
+  verbose: false
+```
+
+**Store output as**: `$STEP_3_OUTPUT`
+
+**Quality Gate**:
+- consistencyScore >= 70 → proceed to review
+- consistencyScore < 70 → flag for detailed review
+
+#### Step 4: Review
+
+**Required Input**: $STEP_3_OUTPUT (verification JSON from Step 3)
+
+**Task invocation**:
+```
+subagent_type: document-reviewer
+prompt: |
+  Review the following PRD considering code verification findings.
+
+  doc_type: PRD
+  target: $STEP_2_OUTPUT
+  mode: composite
+
+  ## Code Verification Results
+  $STEP_3_OUTPUT
+
+  ## Additional Review Focus
+  - Alignment between PRD claims and verification evidence
+  - Resolution recommendations for each discrepancy
+  - Completeness of undocumented feature coverage
+```
+
+**Store output as**: `$STEP_4_OUTPUT`
+
+#### Step 5: Revision (conditional)
+
+**Trigger Conditions** (any one of the following):
+- Review status is "Needs Revision" or "Rejected"
+- Critical discrepancies exist in `$STEP_3_OUTPUT`
+- consistencyScore < 70
+
+**Task invocation**:
+```
+subagent_type: prd-creator
+prompt: |
+  Update PRD based on review feedback.
+
+  Operation Mode: update
+  Existing PRD: $STEP_2_OUTPUT
+
+  ## Review Feedback
+  $STEP_4_OUTPUT
+
+  ## Discrepancies to Address
+  (Extract critical and major discrepancies from $STEP_3_OUTPUT)
+
+  Apply corrections and improvements.
+```
+
+**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status.
+
+#### Unit Completion
+
+- [ ] Review status is "Approved" or "Approved with Conditions"
+- [ ] Human review passed (if enabled in Step 0)
+
+**Next**: Proceed to next unit. After all units → Phase 2.
+
+## Phase 2: Design Doc Generation
+
+*Execute only if Design Docs were requested in Step 0*
+
+**Register in TodoWrite**:
+- Step 6: Design Doc Scope Discovery
+- Per-component processing (Steps 7-10 for each component)
+
+### Step 6: Design Doc Scope Discovery
+
+For each approved PRD:
+
+**Task invocation**:
+```
+subagent_type: scope-discoverer
+prompt: |
+  Discover Design Doc targets within PRD scope.
+
+  scope_type: design-doc
+  existing_prd: $APPROVED_PRD_PATH
+  target_path: $PRD_RELATED_PATHS
+  reference_architecture: $USER_RA_CHOICE
+```
+
+**Store output as**: `$STEP_6_OUTPUT`
+
+**Quality Gate**:
+- At least one component discovered → proceed
+- No components → ask user for hints
+
+### Step 7-10: Per-Component Processing
+
+**Complete Steps 7→8→9→10 for each component before proceeding to the next component.**
+
+#### Step 7: Design Doc Generation
+
+**Task invocation**:
+```
+subagent_type: technical-designer
+prompt: |
+  Create Design Doc for the following component based on existing code.
+
+  Operation Mode: create
+
+  Component: $COMPONENT_NAME (from $STEP_6_OUTPUT)
+  Responsibility: $COMPONENT_RESPONSIBILITY
+  Primary Files: $COMPONENT_PRIMARY_FILES
+  Public Interfaces: $COMPONENT_PUBLIC_INTERFACES
+  Dependencies: $COMPONENT_DEPENDENCIES
+
+  Parent PRD: $APPROVED_PRD_PATH
+
+  Document current architecture. Do not propose changes.
+```
+
+**Store output as**: `$STEP_7_OUTPUT`
+
+#### Step 8: Code Verification
+
+**Task invocation**:
+```
+subagent_type: code-verifier
+prompt: |
+  Verify consistency between Design Doc and code implementation.
+
+  doc_type: design-doc
+  document_path: $STEP_7_OUTPUT
+  code_paths: $COMPONENT_PRIMARY_FILES
+  verbose: false
+```
+
+**Store output as**: `$STEP_8_OUTPUT`
+
+#### Step 9: Review
+
+**Required Input**: $STEP_8_OUTPUT (verification JSON from Step 8)
+
+**Task invocation**:
+```
+subagent_type: document-reviewer
+prompt: |
+  Review the following Design Doc considering code verification findings.
+
+  doc_type: DesignDoc
+  target: $STEP_7_OUTPUT
+  mode: composite
+
+  ## Code Verification Results
+  $STEP_8_OUTPUT
+
+  ## Parent PRD
+  $APPROVED_PRD_PATH
+
+  ## Additional Review Focus
+  - Technical accuracy of documented interfaces
+  - Consistency with parent PRD scope
+  - Completeness of component boundary definitions
+```
+
+**Store output as**: `$STEP_9_OUTPUT`
+
+#### Step 10: Revision (conditional)
+
+Same logic as Step 5, using technical-designer with update mode.
+
+#### Component Completion
+
+- [ ] Review status is "Approved" or "Approved with Conditions"
+- [ ] Human review passed (if enabled in Step 0)
+
+**Next**: Proceed to next component. After all components → Final Report.
+
+## Final Report
+
+Output summary including:
+- Generated documents table (Type, Name, Consistency Score, Review Status)
+- Action items (critical discrepancies, undocumented features, flagged items)
+- Next steps checklist
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Discovery finds nothing | Ask user for project structure hints |
+| Generation fails | Log failure, continue with other units, report in summary |
+| consistencyScore < 50 | Flag for mandatory human review, do not auto-approve |
+| Review rejects after 2 revisions | Stop loop, flag for human intervention |

package/.claude/commands-ja/diagnose.md

@@ -8,20 +8,47 @@ description: 問題を調査し、検証を経て解決策を導出する
 
 **TodoWrite登録**: 実行ステップをTodoWriteに登録し、計画的にタスクを進める
 
+## ステップ0: 問題の構造化（investigator呼び出し前）
+
+### 0.1 問題タイプの判定
+
+| タイプ | 判断基準 |
+|--------|---------|
+| 変更失敗 | 問題発生の前に何らかの変更があったことが示唆されている |
+| 新規発見 | 変更との関連が示唆されていない |
+
+判断に迷う場合は「問題発生の直前に何か変更しましたか？」とユーザーに確認。
+
+### 0.2 変更失敗の場合の情報補完
+
+以下が不明な場合、**AskUserQuestionで質問**してから次に進む：
+- 何を変更したか（原因変更）
+- 何が壊れたか（影響箇所）
+- 両者の関係（共通コンポーネント等）
+
+### 0.3 investigatorプロンプトへの反映
+
+**変更失敗の場合、以下を必須調査項目としてプロンプトに含める**：
+1. 原因変更の内容を詳細に分析
+2. 原因変更と影響箇所の共通点を特定
+3. 原因変更が正しい修正か新たなバグかを判定し、判定結果に基づいて比較基準を選択
+
 ## 診断フロー概要
 
 ```
-問題 → ステップ1:調査 → ステップ2:複雑性判定 → [ステップ3:検証] → ステップ4:解決策導出 → ステップ5:レポート
-                                          ↓
-                                     単純な場合は
-                                     ステップ3スキップ
+問題 → 調査 → 品質判定 → [検証] → 解決策導出
+                    ↓
+               単純な場合は
+               検証スキップ
 ```
 
 **コンテキスト分離**: 各ステップには構造化JSON出力のみを渡す。思考過程は引き継がない。
 
 ## 実行ステップ
 
-### ステップ1: 調査
+以下をTodoWriteに登録して実行：
+
+### ステップ1: 調査（investigator）
 
 **Taskツールでの呼び出し**:
 ```
@@ -31,46 +58,55 @@ prompt: 以下の現象について、関連する情報を網羅的に収集し
 現象: [ユーザーが報告した問題]
 ```
 
-**期待される出力**: 証拠マトリクス、未探索領域のリスト、調査の限界
+**期待される出力**: 証拠マトリクス、比較分析結果、因果追跡結果、未探索領域のリスト、調査の限界
+
+### ステップ2: 品質判定・検証判断
+
+調査出力を確認し判定：
 
-### ステップ2: 複雑性判定
+**調査品質チェック**（出力JSONに以下が含まれているか）:
+- [ ] comparisonAnalysis
+- [ ] 各仮説にcausalChain（停止条件に到達）
+- [ ] 各仮説にcauseCategory
 
-ステップ1の出力を確認し判定：
+**品質不足の場合**: 不足項目を指定して調査を再実行
 
-**ステップ3実行条件（1つでも該当）**:
+**検証実行条件（1つでも該当）**:
 - 2つ以上の仮説が同程度の証拠を持つ
 - 直接証拠がなく間接証拠のみ
 - 未探索領域が2つ以上ある
 - 仮説に反証する証拠が存在する
 - 問題が過去に再発している
+- impactAnalysis.impactScopeに3件以上の該当箇所がある
+- impactAnalysis.recurrenceRiskがhigh
 
-**ステップ3スキップ条件（すべて該当）**:
+**検証スキップ条件（すべて該当）**:
 - 1つの仮説が明らかに優勢（直接証拠あり、反証なし）
 - 未探索領域がほぼない
 - 単発の問題（再発履歴なし）
 
-判定結果をユーザーに報告し、ステップ3をスキップする場合は理由を説明。
+判定結果をユーザーに報告し、検証をスキップする場合は理由を説明。
 
-### ステップ3: 検証（複雑な場合のみ）
+### ステップ3: 検証（verifier）※複雑な問題の場合
 
 **Taskツールでの呼び出し**:
 ```
 subagent_type: verifier
 prompt: 以下の調査結果を検証してください。
 
-調査結果: [ステップ1のJSON出力]
+調査結果: [調査のJSON出力]
 ```
 
 **期待される出力**: 代替仮説（最低3つ）、Devil's Advocate評価、最終結論、信頼度
 
-### ステップ4: 解決策導出
+### ステップ4: 解決策導出（solver）
 
 **Taskツールでの呼び出し**:
 ```
 subagent_type: solver
 prompt: 以下の検証済み結論に基づいて、解決策を導出してください。
 
-結論: [ステップ3またはステップ1の結論部分]
+結論: [検証または調査の結論部分]
 信頼度: [high/medium/low]
 ```
 
@@ -116,8 +152,9 @@ prompt: 以下の検証済み結論に基づいて、解決策を導出してく
 
 ## 完了条件
 
-- [ ] ステップ1: 調査を実行し、証拠マトリクスを取得した
-- [ ] ステップ2: 複雑性判定を行い、結果をユーザーに報告した
-- [ ] ステップ3: （複雑な場合）検証を実行した
-- [ ] ステップ4: 解決策導出を実行した
-- [ ] ステップ5: 最終レポートをユーザーに提示した
+- [ ] 調査を実行し、証拠マトリクス・比較分析・因果追跡を取得した
+- [ ] 調査品質チェックを行い、不足があれば再実行した
+- [ ] 検証判断を行い、結果をユーザーに報告した
+- [ ] （複雑な場合）検証を実行した
+- [ ] 解決策導出を実行した
+- [ ] 最終レポートをユーザーに提示した