commands/gudaspec/plan-review.md

name: GudaSpec: Plan Review description: Review plan structure, write detailed implementation plan with test specifications, and approve. category: GudaSpec tags: [gudaspec, plan, review, detail, tdd, approval] argument-hint: [requirement-id]

Purpose

基于已确认的计划结构，编写详细实施计划，生成测试规格（如适用），多模型审查，最终用户批准。

Core Principles

1. Structure First — 结构已在plan阶段确认，本阶段聚焦细节
2. Test-First When TDD — Level 1-2时，测试规格先于实现细节
3. Interactive Review — 逐Phase与用户确认，非一次性输出
4. Multi-Model Verification — 多模型审查计划完整性
5. Explicit Approval — 必须获得用户明确批准

Guardrails

• MUST load both structure.md and requirement.md first.
• MUST confirm each Phase with user before moving to next.
• MUST generate test specifications if test_level >= 1.
• MUST run multi-model review before final approval.
• NEVER finalize plan with open questions.
• Keep context under 60K tokens.

---

Steps

Step 0: Load Documents

cat gudaspec/plans/<requirement-id>/structure.md
cat gudaspec/research/<requirement-id>/requirement.md

Extract:

• Phase结构
• 测试策略Level
• 约束集
• 技术决策

Step 1: Structure Confirmation

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 计划详细化: <Requirement Title>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

需求ID: <requirement-id>
测试策略: Level <X>

【计划结构回顾】
Phase 1: <name> — <goal>
Phase 2: <name> — <goal>
Phase 3: <name> — <goal>

接下来我将逐Phase编写详细内容。
每个Phase完成后会请您确认。

准备开始？

Step 2: Detail Each Phase (Interactive Loop)

For each Phase:

2.1 Generate Test Specifications (if Level >= 1)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧪 Phase 1 测试规格
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【测试目标】
验证: <what this phase should achieve>

【测试用例】

┌─────────────────────────────────────────────────────────────┐
│ Test 1: <test_name>                                          │
├─────────────────────────────────────────────────────────────┤
│ 场景: <scenario description>                                │
│ 输入: <input>                                               │
│ 期望: <expected output>                                     │
│ 验证: <how to verify>                                       │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Test 2: <test_name>                                          │
├─────────────────────────────────────────────────────────────┤
│ 场景: <edge case>                                           │
│ 输入: <input>                                               │
│ 期望: <expected output>                                     │
│ 验证: <how to verify>                                       │
└─────────────────────────────────────────────────────────────┘

【测试代码骨架】
```python
# tests/test_<module>.py

class TestPhase1<Feature>:
    """Phase 1: <name> 测试"""
    
    def test_<scenario_1>(self):
        """
        场景: <description>
        期望: <expected>
        """
        # Arrange
        <setup code hint>
        
        # Act
        <action code hint>
        
        # Assert
        assert <condition>, "<failure message>"
    
    def test_<scenario_2>(self):
        """边界情况: <description>"""
        # TODO: Implement
        pass

【Property Tests】(if Level 2)

from hypothesis import given, strategies as st

@given(st.text(min_size=1, max_size=100))
def test_<property_name>(input_value):
    """
    Property: <invariant description>
    """
    result = <function>(input_value)
    assert <property_condition>

Use `AskUserQuestions`:

question: "Phase 1 测试规格是否完整？" options: [ "完整，继续编写实现细节", "需要添加更多测试场景", "需要修改某个测试", "测试粒度不合适" ]

### Step 2.2: Write Implementation Details

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📝 Phase 1 变更规格 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【变更清单】

1️⃣ 认证服务扩展

┌─────────────────────────────────────────────────────────────┐ │ 文件: src/auth/service.py │ │ 类型: 修改现有类 │ ├─────────────────────────────────────────────────────────────┤ │ 【接口定义】 │ │ python │ │ async def verify_2fa( │ │ self, │ │ user_id: UUID, │ │ code: str │ │ ) -> bool: │ │ """ │ │ 验证用户的双因素认证码 │ │ │ │ Args: │ │ user_id: 用户唯一标识 │ │ code: 6位TOTP验证码 │ │ │ │ Returns: │ │ 验证成功True，失败False │ │ │ │ Raises: │ │ UserNotFoundError: 用户不存在 │ │ TwoFactorNotEnabledError: 用户未启用2FA │ │ """ │ │ │ ├─────────────────────────────────────────────────────────────┤ │ 【行为规格】 │ │ • 用户不存在 → 抛出 UserNotFoundError │ │ • 用户未启用2FA → 抛出 TwoFactorNotEnabledError │ │ • 验证码正确 → 返回 True，重置失败计数 │ │ • 验证码错误 → 返回 False，增加失败计数 │ │ • 验证窗口 → ±1周期（允许30秒误差） │ ├─────────────────────────────────────────────────────────────┤ │ 【实现要点】 │ │ • 使用现有 TotpService.verify() 方法 │ │ • 遵循 authenticate() 的错误处理模式 │ │ • 失败计数存储于 user.failed_2fa_attempts │ ├─────────────────────────────────────────────────────────────┤ │ 【参考模式】 │ │ • src/auth/service.py:78-95 authenticate() 方法 │ │ • src/auth/totp.py:23 TotpService.verify() 方法 │ ├─────────────────────────────────────────────────────────────┤ │ 关联约束: HC-I-1（复用TotpService）, SC-I-2（错误处理模式） │ │ 关联测试: test_valid_code_passes, test_invalid_code_fails │ └─────────────────────────────────────────────────────────────┘

【注意】: 以上是规格说明，非完整实现代码。 Implementation阶段将基于此规格编写实际代码。

Use `AskUserQuestions`:

question: "Phase 1 实现细节是否清晰完整？" options: [ "清晰，继续Phase 2", "代码变更需要调整", "执行顺序需要修改", "Success Criteria需要补充" ]

#### 2.3 Repeat for Each Phase

Continue until all Phases are detailed.

### Step 3: Multi-Model Review

**Invoke `mcp__codex__codex`:**

Review this implementation plan: [paste complete plan]

Check for:

1. Missing files that should be modified
2. Incorrect dependency order
3. Incomplete success criteria
4. Edge cases not covered by tests

Format: [ISSUE] → [SUGGESTION]

**Invoke `mcp__gemini__gemini`:**

Review this implementation plan: [paste complete plan]

Check for:

1. UI/UX gaps
2. Accessibility issues
3. Component interaction problems
4. Missing manual verification steps

Format: [ISSUE] → [SUGGESTION]

**Present review findings:**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔍 多模型审查结果 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【Codex 发现】 • ⚠️ <issue 1> → 建议: • ✅ 依赖顺序正确 • ✅ 测试覆盖完整

【Gemini 发现】 • ⚠️ <issue 2> → 建议: • ✅ UI变更合理

【已自动修正】 •

【需要您确认】 •

### Step 4: Final Summary & Approval

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 计划总结 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【计划概览】 ┌─────────────────────────────────────────────────────────────┐ │ 需求: │ │ ID: │ │ 测试策略: Level │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Phase 1: │ │ ├─ 文件变更: 个 │ │ ├─ 测试用例: 个 │ │ └─ 验证点: 自动个 + 手动个 │ │ │ │ Phase 2: │ │ ├─ 文件变更: 个 │ │ ├─ 测试用例: 个 │ │ └─ 验证点: 自动个 + 手动个 │ │ │ │ Phase 3: │ │ ├─ 文件变更: 个 │ │ ├─ 测试用例: 个 │ │ └─ 验证点: 自动个 + 手动个 │ │ │ ├─────────────────────────────────────────────────────────────┤ │ 总计: │ │ • 文件变更: 个 │ │ • 测试用例: 个 │ │ • 自动验证: 个 │ │ • 手动验证: 个 │ │ • 风险等级: 中 │ └─────────────────────────────────────────────────────────────┘

【执行流程预览】 Phase 1 → 自动验证 → ⏸️手动确认 → Phase 2 → 自动验证 → ⏸️手动确认 → ...

【回滚计划】 如果任何Phase失败:

Use `AskUserQuestions`:

question: "是否批准此计划？" options: [ "批准，保存完整计划", "需要修改某个Phase", "需要调整整体结构", "有问题需要讨论" ]

### Step 5: Save Complete Plan

Save to: `gudaspec/plans/<requirement-id>/plan.md`

Also save test skeletons (if Level >= 1):

gudaspec/plans//tests/ ├── test_spec.md └── skeletons/ ├── test_phase1.py ├── test_phase2.py └── ...

Update structure.md status: `status: plan-approved`

### Step 6: Completion Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ 计划已批准 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

需求ID:

📁 生成的文件: gudaspec/plans// ├── structure.md (已更新状态) ├── plan.md (完整计划) ⭐ └── tests/ ├── test_spec.md (测试规格) └── skeletons/ (测试骨架代码)

📊 计划摘要: ┌─────────────────────────────────────────┐ │ Phases: [N] │ │ 文件变更: [X] │ │ 测试用例: [Y] │ │ 测试策略: Level [Z] │ └─────────────────────────────────────────┘

📋 下一步操作:

1. 输入 /clear 清空当前上下文
2. 输入 /gudaspec:implementation gudaspec/plans//plan.md

⚠️ 实施阶段提示: • 将逐Phase执行，每Phase有明确的停止点 • 测试将在实现前/后运行（取决于TDD Level） • 每个Phase自动验证通过后等待您的手动确认

---

## Exit Criteria

- [ ] Structure document loaded and confirmed
- [ ] All Phases detailed with implementation steps
- [ ] Test specifications generated (if Level >= 1)
- [ ] Multi-model review completed and issues addressed
- [ ] User explicitly approved the plan
- [ ] plan.md saved with all details
- [ ] Test skeletons saved (if applicable)
- [ ] User directed to /gudaspec:implementation

<!-- GUDASPEC:PLAN-REVIEW:END -->