review

/review - 全面代码审查

描述

使用并行的专业子 Agent 进行全方位代码审查。每位专业人员分析一个特定维度，汇总所有发现后，由 /qa-gate 给出最终门禁判定。

主要功能：

• 并行的专业子 Agent，进行全面分析
• 需求可追溯性（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 目录名称（例如，epic-6-wishlist）或完整目录路径
• --branch - 在没有故事引用的情况下审查当前分支
• --status - 按状态筛选故事（例如，Draft、In Progress、Approved）——仅用于目录审查
• --quick - 仅运行必需检查，跳过深入的专业审查
• --fix - 在安全的情况下自动修复问题（重构）
• --files - 仅审查指定文件
• --no-gate - 跳过 /qa-gate 调用，仅返回发现

---

执行说明

重要：使用 Task 工具启动并行子 Agent。使用 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 目录名称（例如，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- 开头的文件（Epic 定义文件）
5. 对剩余的每个文件进行读取和提取：
   • Frontmatter（如果存在）
   • 状态字段（来自 frontmatter 或文件中的 status: 行）
6. 如果提供了 --status 筛选条件，则仅包含状态匹配的故事
7. 按文件名排序故事（自然排序）
8. 为每个故事创建一个待办事项

单个故事转到阶段 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. 确定审查范围（要分析的文件）

风险评估（决定审查深度）： 出现以下情况时自动升级为深入审查：

• 涉及身份验证、支付或安全文件
• 未添加测试
• Diff 超过 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. 将待办事项标记为已完成，然后继续下一个故事

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：启动专家子 Agent

重要：使用 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 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. 提供可执行的后续步骤

---

子 Agent 架构

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 集成
• 仅限自动化检查