review

/review - 包括的なコードレビュー

説明

専門分野ごとのサブエージェントを並行して使い、コードをあらゆる観点からレビューします。各専門家が特定の側面を分析し、結果を集約したうえで、/qa-gate が最終的なゲート判定を行います。

主な機能：

• 徹底的な分析を行う専門分野ごとのサブエージェントを並行して実行
• 要件のトレーサビリティ（AC → テストのマッピング）
• 安全な場合の積極的なリファクタリング
• 技術的負債の特定
• 結果を包括的に集約
• /qa-gate による自動ゲート判定

使用方法

# Review a single story by number
/review 3.1.5

# Review a single story by file path
/review docs/stories/epic-6-wishlist/wish-2002-add-item-flow.md

# Review current branch (no story)
/review --branch

# Review all stories in an epic directory (shorthand)
/review epic-6-wishlist

# Review all stories in a directory (full path)
/review docs/stories/epic-6-wishlist/

# Review directory, only stories with specific status
/review epic-6-wishlist --status=Draft

# Quick review (skip deep specialists)
/review 3.1.5 --quick

# Review with auto-fix enabled
/review 3.1.5 --fix

# Review specific files only
/review --files src/auth/**/*.ts

# Skip gate decision (findings only)
/review 3.1.5 --no-gate

パラメーター

• target - ストーリー番号（例：3.1.5）、ストーリーファイルのパス、エピックディレクトリ名（例：epic-6-wishlist）、またはディレクトリのフルパス
• --branch - ストーリーを指定せず、現在のブランチをレビューします
• --status - ステータス（例：Draft、In Progress、Approved）でストーリーを絞り込みます（ディレクトリレビューでのみ使用）
• --quick - 必須チェックのみを実行し、詳細分析を行う専門エージェントを省略します
• --fix - 安全な場合に問題を自動修正します（リファクタリング）
• --files - 指定したファイルのみをレビューします
• --no-gate - /qa-gate の呼び出しを省略し、指摘事項のみを返します

---

実行手順

重要：Task ツールを使用してサブエージェントを並行して起動してください。進捗の追跡には TodoWrite を使用してください。

---

フェーズ 0：初期化とモードの判定

target 引数に基づいて操作モードを自動検出します：

# Detection logic:
if target is None or target == "--branch":
    mode = "branch_review"
elif target.endswith(".md"):
    mode = "single_story"  # File path to specific story
elif is_directory(target) or target.startswith("epic-"):
    mode = "directory_review"
elif is_story_number(target):  # e.g., "3.1.5" or "2002"
    mode = "single_story"
else:
    # Try to resolve as story number, fall back to directory
    mode = "single_story"

モード A：単一ストーリーのレビュー（デフォルト）

以下の場合に実行されます：

• ストーリー番号（例：3.1.5、2002）
• ストーリーファイルのパス（例：docs/stories/epic-6-wishlist/wish-2002-add-item-flow.md）
• --branch フラグ

モード B：ディレクトリレビュー（新規）

以下の場合に実行されます：

• エピックディレクトリ名（例：epic-6-wishlist）— docs/stories/ が自動的に先頭に追加されます
• ディレクトリのフルパス（例：docs/stories/epic-6-wishlist/）
• .md ファイルを含むディレクトリを指すパス

TodoWrite([
  { content: "Scan directory for stories", status: "in_progress", activeForm: "Scanning directory" },
  { content: "Filter stories by status", status: "pending", activeForm: "Filtering stories" },
  { content: "Review each story sequentially", status: "pending", activeForm: "Reviewing stories" },
  { content: "Generate summary report", status: "pending", activeForm: "Generating summary" }
])

ディレクトリのスキャン：

1. ディレクトリのパスを解決します：
   • epic- で始まる場合：docs/stories/ を先頭に追加 → docs/stories/epic-6-wishlist/
   • フルパスが指定されている場合：そのまま使用
   • 相対パスの場合：作業ディレクトリを基準に解決
2. ディレクトリの存在を確認し、存在しない場合はエラーにします
3. ディレクトリ内のすべての .md ファイルを検索します：Glob(pattern: "*.md", path: {DIR_PATH})
4. 除外対象のファイル／ディレクトリを除外します：
   • _legacy/ サブディレクトリ内のファイルをスキップ
   • IMPLEMENTATION_ORDER.md をスキップ
   • README.md をスキップ
   • EPIC- で始まるファイル（エピック定義ファイル）をスキップ
5. 残った各ファイルを読み込み、以下を抽出します：
   • フロントマター（存在する場合）
   • ステータスフィールド（フロントマター、またはファイル内の status: 行から）
6. --status フィルターが指定されている場合、ステータスが一致するストーリーのみを含めます
7. ファイル名の自然順でストーリーを並べ替えます
8. ストーリーごとに 1 項目を含む Todo リストを作成します

単一ストーリーの場合はフェーズ 0A、ディレクトリの場合はフェーズ 0B に進みます。

---

フェーズ 0A：コンテキストの収集（単一ストーリー）

単一ストーリーのレビューの場合：

TodoWrite([
  { content: "Gather review context", status: "in_progress", activeForm: "Gathering context" },
  { content: "Run required checks", status: "pending", activeForm: "Running checks" },
  { content: "Spawn specialist sub-agents", status: "pending", activeForm: "Spawning specialists" },
  { content: "Aggregate findings", status: "pending", activeForm: "Aggregating findings" },
  { content: "Run qa-gate", status: "pending", activeForm: "Running qa-gate" },
  { content: "Update story file", status: "pending", activeForm: "Updating story" }
])

コンテキストを収集します：

1. ストーリーが指定されている場合は、ストーリーファイルを読み込み、以下を抽出します：
   • 受け入れ条件
   • タスクリスト
   • ファイルリスト（存在する場合）
   • 過去の QA 結果
2. 変更されたファイルの一覧を取得します：git diff --name-only origin/main
3. プロジェクトのガイドラインとして CLAUDE.md を読み込みます
4. レビュー範囲（分析対象ファイル）を決定します

リスク評価（レビューの深さを決定）： 以下の場合、詳細なレビューに自動的に切り替えます：

• 認証／決済／セキュリティ関連のファイルが変更されている
• テストが追加されていない
• 差分が 500 行を超える
• 前回のゲート判定が FAIL または CONCERNS
• ストーリーの受け入れ条件が 5 つを超える

フェーズ 1 に進みます。

---

フェーズ 0B：ディレクトリの処理（複数のストーリー）

ディレクトリをレビューする場合：

stories_to_review = [{story_path}, {story_path}, ...]  # From Phase 0

TodoWrite([
  { content: "Review {story_1}", status: "in_progress", activeForm: "Reviewing {story_1}" },
  { content: "Review {story_2}", status: "pending", activeForm: "Reviewing {story_2}" },
  { content: "Review {story_3}", status: "pending", activeForm: "Reviewing {story_3}" },
  # ... one per story
  { content: "Generate summary report", status: "pending", activeForm: "Generating summary" }
])

stories_to_review 内の各ストーリーについて：

1. ストーリーファイルを読み込み、以下を抽出します：

   • ストーリー ID／番号
   • タイトル
   • ステータス
   • 受け入れ基準
   • タスクリスト
   • 以前のレビューでの指摘事項（ある場合）

2. このストーリーに対してフェーズ 0A から 7 を実行します（変更されたフェーズ 7 については以下を参照）

3. todo を完了としてマークし、次のストーリーに進みます

4. すべてのストーリーの処理後、フェーズ 8B（サマリーレポート）に進みます

重要：ストーリーは並列ではなく、順番に処理してください。これにより、次のストーリーに進む前に各ストーリーファイルへ指摘事項を追記できます。

各ストーリーについてフェーズ 0A に進み、その後、各フェーズを続けて実行してください。

---

フェーズ 1：必須チェック

まず以下を実行します（失敗した場合は処理をブロックします）：

pnpm test --filter='...[origin/main]'
pnpm check-types --filter='...[origin/main]'
pnpm lint --filter='...[origin/main]'

いずれかが失敗し、--fix が設定されている場合：

• lint の問題の自動修正を試します：pnpm lint --fix
• チェックを再実行します

それでも失敗する場合： 報告して続行します（ゲートの判定に影響します）

---

フェーズ 2：専門サブエージェントの起動

重要：run_in_background: true を使用して、すべての専門家を並列で起動してください

2.1 要件トレーサビリティ専門家

Task(
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Requirements traceability",
  run_in_background: true,
  prompt: "You are a requirements traceability specialist.

           Story file: {STORY_FILE_PATH}
           Changed files: {CHANGED_FILES}

           For each acceptance criterion in the story:
           1. Find the test(s) that validate it
           2. Document the mapping using Given-When-Then format
           3. Identify any AC without test coverage

           T-SHIRT SIZE ESTIMATE (from requirements perspective):
           Based on the number of acceptance criteria, their complexity, and test coverage gaps:
           - XS: 1-2 simple ACs, all covered
           - S: 3-4 ACs, mostly covered
           - M: 5-7 ACs, some gaps
           - L: 8-10 ACs, significant gaps
           - XL: 11+ ACs, many gaps
           - XXL: 15+ ACs, extensive gaps or highly complex criteria

           Output format:
           ```yaml
           traceability:
             t_shirt_size: XS|S|M|L|XL|XXL
             size_rationale: 'Brief explanation of size estimate'
             covered:
               - ac: 1
                 test_file: src/__tests__/auth.test.ts
                 test_name: 'should validate login credentials'
                 given_when_then: 'Given valid credentials, When login called, Then returns token'
             gaps:
               - ac: 3
                 description: 'No test for session timeout handling'
                 severity: medium
                 suggested_test: 'Add test for session expiry behavior'
           ```"
)

2.2 コード品質専門家

Task(
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Code quality review",
  run_in_background: true,
  prompt: "You are a code quality specialist.

           Project guidelines: {CLAUDE_MD_CONTENT}
           Changed files: {CHANGED_FILES}

           Analyze for:
           1. Architecture and design patterns
           2. Code duplication
           3. Refactoring opportunities
           4. Best practices adherence
           5. CLAUDE.md compliance (Zod schemas, @repo/ui, @repo/logger, no barrel files)

           T-SHIRT SIZE ESTIMATE (from code quality/complexity perspective):
           Based on code complexity, architectural impact, and refactoring needs:
           - XS: Simple, isolated changes, minimal complexity
           - S: Straightforward implementation, few files touched
           - M: Moderate complexity, some architectural considerations
           - L: Complex logic, multiple components/patterns involved
           - XL: Significant architectural changes, cross-cutting concerns
           - XXL: Major refactoring or system-wide impact

           For each finding:
           - id: QUAL-{NNN}
           - severity: low|medium|high
           - finding: Description
           - file: File path
           - line: Line number
           - suggested_action: How to fix
           - can_auto_fix: true|false

           Output format:
           ```yaml
           code_quality:
             t_shirt_size: XS|S|M|L|XL|XXL
             size_rationale: 'Brief explanation of size estimate'
             complexity_score: 1-10
             findings:
               - id: QUAL-001
                 severity: medium
                 finding: '...'
                 # ... rest of fields
           ```"
)

2.3 セキュリティ専門家

Task(
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Security review",
  run_in_background: true,
  prompt: "You are a security specialist.

           Changed files: {CHANGED_FILES}

           Check for:
           - Authentication/authorization issues
           - Injection vulnerabilities (SQL, XSS, command)
           - Sensitive data exposure
           - OWASP Top 10 issues
           - Hardcoded secrets or credentials
           - Insecure dependencies

           T-SHIRT SIZE ESTIMATE (from security risk perspective):
           Based on security surface area, risk level, and required mitigations:
           - XS: No security implications, read-only operations
           - S: Minor security considerations, standard auth checks
           - M: Moderate security requirements, data validation needed
           - L: Significant security impact, auth/authz critical
           - XL: High-risk features (payments, PII, admin functions)
           - XXL: Critical security features requiring extensive hardening

           For each finding:
           - id: SEC-{NNN}
           - severity: low|medium|high
           - finding: Description
           - file: File path
           - line: Line number
           - cwe: CWE reference if applicable
           - suggested_action: How to fix

           Output format:
           ```yaml
           security:
             t_shirt_size: XS|S|M|L|XL|XXL
             size_rationale: 'Brief explanation of size estimate'
             risk_level: low|medium|high|critical
             findings:
               - id: SEC-001
                 severity: high
                 finding: '...'
                 # ... rest of fields
           ```"
)

2.4 パフォーマンス専門家

Task(
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Performance review",
  run_in_background: true,
  prompt: "You are a performance specialist.

           Changed files: {CHANGED_FILES}

           Check for:
           - N+1 query patterns
           - Missing database indexes
           - Unnecessary re-renders in React
           - Large bundle imports
           - Missing memoization (useMemo, useCallback, React.memo)
           - Inefficient algorithms
           - Memory leaks

           T-SHIRT SIZE ESTIMATE (from performance optimization perspective):
           Based on performance complexity and optimization requirements:
           - XS: Minimal performance considerations, simple operations
           - S: Basic performance best practices sufficient
           - M: Some optimization needed (memoization, indexes)
           - L: Significant performance work (query optimization, caching)
           - XL: Complex performance requirements (real-time, large datasets)
           - XXL: Critical performance engineering (sub-second SLAs, scale challenges)

           For each finding:
           - id: PERF-{NNN}
           - severity: low|medium|high
           - finding: Description
           - file: File path
           - estimated_impact: Description of performance impact
           - suggested_action: How to fix

           Output format:
           ```yaml
           performance:
             t_shirt_size: XS|S|M|L|XL|XXL
             size_rationale: 'Brief explanation of size estimate'
             performance_risk: low|medium|high
             findings:
               - id: PERF-001
                 severity: medium
                 finding: '...'
                 # ... rest of fields
           ```"
)

2.5 アクセシビリティ専門家

Task(
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Accessibility review",
  run_in_background: true,
  prompt: "You are an accessibility specialist.

           Changed files: {CHANGED_FILES}

           Check for:
           - WCAG 2.1 AA compliance
           - Keyboard navigation support
           - Screen reader compatibility
           - Missing ARIA labels/roles
           - Color contrast issues
           - Focus management
           - Form labels and error messages

           T-SHIRT SIZE ESTIMATE (from accessibility perspective):
           Based on UI complexity and a11y requirements:
           - XS: No UI changes, or simple read-only content
           - S: Basic UI with standard components (buttons, text)
           - M: Interactive UI (forms, modals) requiring a11y attention
           - L: Complex UI (data tables, multi-step flows, drag-drop)
           - XL: Rich interactions (custom widgets, animations, dynamic content)
           - XXL: Highly complex UI requiring extensive a11y engineering

           For each finding:
           - id: A11Y-{NNN}
           - severity: low|medium|high
           - finding: Description
           - file: File path
           - wcag_criterion: WCAG reference (e.g., 1.4.3)
           - suggested_action: How to fix

           Output format:
           ```yaml
           accessibility:
             t_shirt_size: XS|S|M|L|XL|XXL
             size_rationale: 'Brief explanation of size estimate'
             ui_complexity: low|medium|high
             findings:
               - id: A11Y-001
                 severity: high
                 finding: '...'
                 # ... rest of fields
           ```"
)

2.6 テストカバレッジ専門家

Task(
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Test coverage analysis",
  run_in_background: true,
  prompt: "You are a test coverage specialist.

           Changed files: {CHANGED_FILES}
           Test files: {TEST_FILES}

           Analyze:
           1. Test coverage for changed code
           2. Test quality and maintainability
           3. Edge cases and error scenarios
           4. Mock/stub appropriateness
           5. Test level appropriateness (unit vs integration vs e2e)

           T-SHIRT SIZE ESTIMATE (from testing perspective):
           Based on testing complexity and coverage requirements:
           - XS: Minimal testing needed, simple assertions
           - S: Basic unit tests sufficient (1-2 test files)
           - M: Moderate testing (unit + some integration tests)
           - L: Comprehensive testing (unit + integration + edge cases)
           - XL: Extensive testing (e2e, multiple scenarios, complex mocks)
           - XXL: Critical path requiring exhaustive test coverage

           For each finding:
           - id: TEST-{NNN}
           - severity: low|medium|high
           - finding: Description
           - file: File being tested (or missing tests)
           - suggested_action: What tests to add/improve

           Output format:
           ```yaml
           test_coverage:
             t_shirt_size: XS|S|M|L|XL|XXL
             size_rationale: 'Brief explanation of size estimate'
             test_complexity: low|medium|high
             findings:
               - id: TEST-001
                 severity: medium
                 finding: '...'
                 # ... rest of fields
           ```"
)

2.7 技術的負債の専門家

Task(
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Technical debt assessment",
  run_in_background: true,
  prompt: "You are a technical debt specialist.

           Changed files: {CHANGED_FILES}

           Identify:
           1. Accumulated shortcuts or TODOs
           2. Missing tests
           3. Outdated patterns or dependencies
           4. Architecture violations
           5. Code that should be refactored
           6. Documentation gaps

           T-SHIRT SIZE ESTIMATE (from tech debt/maintenance perspective):
           Based on long-term maintenance burden and tech debt:
           - XS: Clean implementation, no debt added
           - S: Minimal debt, well-documented
           - M: Some shortcuts taken, minor debt
           - L: Notable tech debt or maintenance concerns
           - XL: Significant debt that will require future cleanup
           - XXL: Major tech debt or legacy pattern perpetuation

           For each finding:
           - id: DEBT-{NNN}
           - severity: low|medium|high
           - finding: Description
           - file: File path
           - estimated_effort: small|medium|large
           - suggested_action: How to address

           Output format:
           ```yaml
           technical_debt:
             t_shirt_size: XS|S|M|L|XL|XXL
             size_rationale: 'Brief explanation of size estimate'
             maintenance_burden: low|medium|high
             findings:
               - id: DEBT-001
                 severity: low
                 finding: '...'
                 # ... rest of fields
           ```"
)

---

フェーズ 3：結果の収集

すべての専門家の完了を待ちます：

results = {
  traceability: TaskOutput(task_id: "{traceability_id}"),
  code_quality: TaskOutput(task_id: "{quality_id}"),
  security: TaskOutput(task_id: "{security_id}"),
  performance: TaskOutput(task_id: "{performance_id}"),
  accessibility: TaskOutput(task_id: "{accessibility_id}"),
  test_coverage: TaskOutput(task_id: "{coverage_id}"),
  technical_debt: TaskOutput(task_id: "{debt_id}")
}

---

フェーズ 4：指摘事項の集約

すべての指摘事項を統一された構造にまとめます：

review_summary:
  story: "{STORY_NUM}"
  reviewed_at: "{ISO-8601}"
  files_analyzed: {count}

  t_shirt_sizing:
    recommended_size: M  # Synthesized from all specialists
    confidence: high|medium|low
    specialist_estimates:
      requirements: { size: M, rationale: "..." }
      code_quality: { size: L, rationale: "..." }
      security: { size: S, rationale: "..." }
      performance: { size: M, rationale: "..." }
      accessibility: { size: M, rationale: "..." }
      test_coverage: { size: L, rationale: "..." }
      technical_debt: { size: M, rationale: "..." }
    size_breakdown:
      XS: 0 specialists
      S: 1 specialist
      M: 4 specialists
      L: 2 specialists
      XL: 0 specialists
      XXL: 0 specialists
    synthesis_rationale: |
      Final size recommendation based on:
      - Modal size: M (4/7 specialists)
      - Outliers: Code Quality (L), Test Coverage (L) due to [reason]
      - Risk factors: [key considerations]
      - Recommended: M with awareness of testing complexity

  checks:
    tests: { status: PASS|FAIL }
    types: { status: PASS|FAIL }
    lint: { status: PASS|FAIL }

  findings:
    total: {count}
    by_severity:
      high: {count}
      medium: {count}
      low: {count}
    by_category:
      security: {count}
      performance: {count}
      accessibility: {count}
      code_quality: {count}
      test_coverage: {count}
      technical_debt: {count}
      requirements: {count}

  traceability:
    ac_total: {count}
    ac_covered: {count}
    ac_gaps: {count}

  all_findings:
    - id: SEC-001
      category: security
      severity: high
      finding: "..."
      file: "..."
      suggested_action: "..."
    # ... all findings sorted by severity

T シャツサイズを統合します：

1. すべての専門家の見積もりを収集します：

   • 各専門家の出力から t_shirt_size を抽出します
   • 各見積もりの根拠を抽出します

2. 最頻サイズ（最も一般的なサイズ）を算出します：

   • 各サイズの出現回数を数えます
   • 最も頻度の高いサイズを特定します

3. 外れ値を特定します：

   • 最頻サイズから 1 サイズを超えて離れた見積もりにフラグを付けます
   • 専門家の意見が一致しない理由を記録します

4. 重み付けのロジックを適用します：

   • セキュリティ／要件：XL または XXL の場合、より高い重みを付けます（リスクベース）
   • コード品質：アーキテクチャの複雑さがある場合、より高い重みを付けます
   • テストカバレッジ：工数の見積もりに考慮します
   • 技術的負債：XXL でない限り、重みを低くします

5. 最終的な推奨をまとめます：

   • 最頻サイズを起点にします
   • リスクの高い外れ値（セキュリティが XL／XXL）の場合はサイズを引き上げます
   • 複数の専門家が複雑さを指摘している場合はサイズを引き上げます
   • 意見の一致度に基づいて信頼度を設定します：
     • 高：5 人以上の専門家が一致
     • 中：3～4 人の専門家が一致
     • 低：意見のばらつきが大きく、明確な最頻サイズがない

6. 統合の根拠を記録します：

   • 最終サイズの選択理由を説明します
   • 主なリスク要因を挙げます
   • 注意点や警告があれば記載します

指摘事項の重複を排除します：

• 異なる専門家からの類似した指摘事項を統合します
• 重複がある場合は、最も高い重大度を維持します

---

フェーズ 5：自動修正（--fix が有効な場合）

can_auto_fix: true の指摘事項について：

Task(
  subagent_type: "general-purpose",
  description: "Apply safe refactoring",
  prompt: "Apply these safe fixes:

           {FIXABLE_FINDINGS}

           Project guidelines: {CLAUDE_MD_CONTENT}

           For each fix:
           1. Make the change
           2. Run tests to verify
           3. Commit with message: 'refactor: {description}'

           Report what was fixed and what was skipped."
)

修正後に必須チェックを再実行します。

---

フェーズ 6：QA ゲートの実行

--no-gate が指定されていない場合：

Invoke /qa-gate skill with:
- Story number (if provided)
- Aggregated findings
- Check results

The /qa-gate skill will:
- Determine gate decision (PASS/CONCERNS/FAIL)
- Create gate file at docs/qa/gates/{story}-{slug}.yml
- Return gate status

---

フェーズ 7：ストーリーファイルの更新

レビュー指摘事項のセクションをストーリーファイルに追記します：

ストーリーファイルに ## Review Findings セクションがすでにあるか確認します：

• ある場合：更新した指摘事項で置き換えます
• ない場合：ファイルの末尾に追記します

## Review Findings

> **Review Date:** {ISO-8601}
> **Reviewed By:** Claude Code
> **Gate:** {PASS|CONCERNS|FAIL} (score: {score}/100)
> **Gate File:** docs/qa/gates/{story}-{slug}.yml

### T-Shirt Size Estimate

**Recommended Size: {M}** (Confidence: {high|medium|low})

**Specialist Breakdown:**
| Specialist | Size | Rationale |
|------------|------|-----------|
| Requirements | M | 5-7 ACs with some test gaps |
| Code Quality | L | Moderate complexity, architectural considerations |
| Security | S | Standard auth checks, low risk |
| Performance | M | Some optimization needed (memoization) |
| Accessibility | M | Interactive UI requiring a11y attention |
| Test Coverage | L | Comprehensive testing needed (unit + integration) |
| Tech Debt | M | Minor shortcuts, well-documented |

**Size Distribution:** XS: 0, S: 1, **M: 4**, L: 2, XL: 0, XXL: 0

**Synthesis:**
Modal size is M (4/7 specialists). Code Quality and Test Coverage flagged as L due to architectural complexity and comprehensive testing requirements. Overall recommendation: **M** with awareness that testing effort may push toward upper end of estimate.

---

### Summary

- **Files Analyzed:** {count}
- **Total Findings:** {count} (high: {N}, medium: {N}, low: {N})
- **Traceability:** {N}/{M} acceptance criteria have test coverage

### Required Checks

| Check | Status |
|-------|--------|
| Tests | {PASS/FAIL} |
| Types | {PASS/FAIL} |
| Lint  | {PASS/FAIL} |

### Requirements Traceability

{If traceability gaps found:}
- **[REQ-001] {severity}:** {finding}
  - **File:** {file or N/A}
  - **Action:** {suggested_action}

{If no gaps:}
✓ All acceptance criteria have test coverage

### Code Quality

{For each finding:}
- **[QUAL-001] {severity}:** {finding}
  - **File:** {file}:{line}
  - **Action:** {suggested_action}

{If no findings:}
✓ No issues found

### Security

{For each finding:}
- **[SEC-001] {severity}:** {finding}
  - **File:** {file}:{line}
  - **CWE:** {cwe_reference}
  - **Action:** {suggested_action}

{If no findings:}
✓ No issues found

### Performance

{For each finding:}
- **[PERF-001] {severity}:** {finding}
  - **File:** {file}:{line}
  - **Impact:** {estimated_impact}
  - **Action:** {suggested_action}

{If no findings:}
✓ No issues found

### Accessibility

{For each finding:}
- **[A11Y-001] {severity}:** {finding}
  - **File:** {file}:{line}
  - **WCAG:** {wcag_criterion}
  - **Action:** {suggested_action}

{If no findings:}
✓ No issues found

### Test Coverage

{For each finding:}
- **[TEST-001] {severity}:** {finding}
  - **File:** {file}
  - **Action:** {suggested_action}

{If no findings:}
✓ No issues found

### Technical Debt

{For each finding:}
- **[DEBT-001] {severity}:** {finding}
  - **File:** {file}:{line}
  - **Effort:** {estimated_effort}
  - **Action:** {suggested_action}

{If no findings:}
✓ No issues found

{If --fix was used:}
### Refactoring Applied

- **{file}:** {what was changed and why}

### Recommendation

{If PASS:}
✓ **Ready for Done** - All checks passed, no blocking issues.

{If CONCERNS:}
⚠ **Review Required** - Address medium-severity issues and proceed with awareness.

{If FAIL:}
✗ **Changes Required** - Address high-severity issues before proceeding.

---

重要：

• ## Review Findings セクションがすでにある場合は、Edit ツールを使って置き換えます
• 指摘事項を専門家のカテゴリ別に整理します
• 指摘事項がないカテゴリには「✓ 問題は見つかりませんでした」と表示します
• 指摘事項を重大度の高い順（高 → 中 → 低）に並べます
• 簡単に参照できるよう、ファイルパスと行番号を含めます

---

フェーズ 8A：ユーザーへの報告（単一のストーリー）

単一のストーリーをレビューする場合：

═══════════════════════════════════════════════════════════════════
  Code Review Complete: {STORY_NUM} - {STORY_TITLE}
═══════════════════════════════════════════════════════════════════

Files Analyzed: {N}
Time Taken: {duration}

T-SHIRT SIZE ESTIMATE
  Recommended: M (Confidence: high)
  Breakdown: XS:0 S:1 M:4 L:2 XL:0 XXL:0

  Requirements:    M  (5-7 ACs with some gaps)
  Code Quality:    L  (Moderate complexity, architectural considerations)
  Security:        S  (Standard auth, low risk)
  Performance:     M  (Some optimization needed)
  Accessibility:   M  (Interactive UI, a11y attention required)
  Test Coverage:   L  (Comprehensive testing needed)
  Tech Debt:       M  (Minor shortcuts, well-documented)

REQUIRED CHECKS
  Tests:    {PASS|FAIL}
  Types:    {PASS|FAIL}
  Lint:     {PASS|FAIL}

SPECIALIST FINDINGS ({total} total)
  Security:       {N} issues ({high}H {medium}M {low}L) → Size: S
  Performance:    {N} issues ({high}H {medium}M {low}L) → Size: M
  Accessibility:  {N} issues ({high}H {medium}M {low}L) → Size: M
  Code Quality:   {N} issues ({high}H {medium}M {low}L) → Size: L
  Test Coverage:  {N} issues ({high}H {medium}M {low}L) → Size: L
  Technical Debt: {N} issues ({high}H {medium}M {low}L) → Size: M

REQUIREMENTS TRACEABILITY
  {covered}/{total} acceptance criteria have test coverage
  {gaps} gaps identified

TOP ISSUES
  1. [SEC-001] high: {finding}
  2. [PERF-001] medium: {finding}
  ...

{If --fix was used:}
REFACTORING APPLIED
  - {file}: {change}
  ...

GATE DECISION
  Status: {PASS|CONCERNS|FAIL}
  Gate File: docs/qa/gates/{story}-{slug}.yml

{If FAIL:}
RECOMMENDATION: Address high-severity issues before proceeding.

{If CONCERNS:}
RECOMMENDATION: Review medium-severity issues and proceed with awareness.

{If PASS:}
RECOMMENDATION: Ready for merge.

FINDINGS LOCATION
  Story file updated: {STORY_FILE_PATH}

═══════════════════════════════════════════════════════════════════

---

フェーズ 8B：サマリーレポート（ディレクトリレビュー）

ディレクトリ内のすべてのストーリーのレビュー完了後：

═══════════════════════════════════════════════════════════════════
  Epic Review Complete: {EPIC_NAME}
═══════════════════════════════════════════════════════════════════

Stories Reviewed: {N}
Total Time: {duration}

GATE SUMMARY
  PASS:     {N} stories
  CONCERNS: {N} stories
  FAIL:     {N} stories

T-SHIRT SIZE DISTRIBUTION
  XS:  {N} stories
  S:   {N} stories
  M:   {N} stories
  L:   {N} stories
  XL:  {N} stories
  XXL: {N} stories

  Epic Effort Estimate: {sum of sizes} → ~{estimate} story points

FINDINGS BY STORY

┌─────────────────────────────────────────────────────────────────┐
│ {story-1-id} - {story-1-title}
├─────────────────────────────────────────────────────────────────┤
│ Size:     M (Confidence: high)
│ Gate:     {PASS|CONCERNS|FAIL}
│ Findings: {total} ({high}H {medium}M {low}L)
│ File:     {story_file_path}
│ Gate:     docs/qa/gates/{story-1}-{slug}.yml
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ {story-2-id} - {story-2-title}
├─────────────────────────────────────────────────────────────────┤
│ Gate:     {PASS|CONCERNS|FAIL}
│ Findings: {total} ({high}H {medium}M {low}L)
│ File:     {story_file_path}
│ Gate:     docs/qa/gates/{story-2}-{slug}.yml
└─────────────────────────────────────────────────────────────────┘

{... for each story}

AGGREGATE STATISTICS

Total Findings: {total_across_all_stories}
  High:    {N}
  Medium:  {N}
  Low:     {N}

By Category:
  Security:       {N} findings across {M} stories
  Performance:    {N} findings across {M} stories
  Accessibility:  {N} findings across {M} stories
  Code Quality:   {N} findings across {M} stories
  Test Coverage:  {N} findings across {M} stories
  Technical Debt: {N} findings across {M} stories

MOST COMMON ISSUES (Top 5)

1. {issue_type}: {N} occurrences across {M} stories
2. {issue_type}: {N} occurrences across {M} stories
3. {issue_type}: {N} occurrences across {M} stories
4. {issue_type}: {N} occurrences across {M} stories
5. {issue_type}: {N} occurrences across {M} stories

RECOMMENDATION

{If any FAIL:}
⚠ {N} stories require changes before proceeding.
  → Review findings in each story file and address blocking issues.

{If any CONCERNS but no FAIL:}
⚠ {N} stories have concerns.
  → Review findings and proceed with awareness of identified issues.

{If all PASS:}
✓ All stories passed review! Ready for implementation or merge.

NEXT STEPS

Review detailed findings in each story file:
{For each story with FAIL or CONCERNS:}
  - {story_file_path}

═══════════════════════════════════════════════════════════════════

集計分析：

1. ゲートのステータス（PASS/CONCERNS/FAIL）ごとにストーリー数を集計します
2. すべてのストーリーの指摘事項の合計数を集計します
3. ストーリー全体で最も多く見られる問題の種類を特定します
4. 実行可能な次のステップを提示します

---

サブエージェントのアーキテクチャ

Main Orchestrator (/review)
    │
    ├─▶ Context Gathering (inline)
    │
    ├─▶ Required Checks (inline)
    │   ├── pnpm test
    │   ├── pnpm check-types
    │   └── pnpm lint
    │
    ├─▶ Specialist Sub-Agents (parallel, haiku)
    │   ├── Requirements Traceability
    │   ├── Code Quality
    │   ├── Security
    │   ├── Performance
    │   ├── Accessibility
    │   ├── Test Coverage
    │   └── Technical Debt
    │
    ├─▶ Aggregation (inline)
    │
    ├─▶ Auto-Fix (optional, general-purpose)
    │
    └─▶ /qa-gate (produces gate file)

---

問題 ID のプレフィックス

プレフィックス	専門分野
SEC-	セキュリティ
PERF-	パフォーマンス
A11Y-	アクセシビリティ
QUAL-	コード品質
TEST-	テストカバレッジ
DEBT-	技術的負債
REQ-	要件のトレーサビリティ

---

使用する場面

/review（包括的）

• マージ前のレビュー
• ストーリー完了時のレビュー
• 主要機能のレビュー
• セキュリティ上重要な変更

/review --quick

• 小規模な変更
• ドキュメントの更新
• 軽微な修正

/qa-gate（単独）

• 迅速な合否判定
• CI/CD との統合
• 自動チェックのみ