--- 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 ```bash cat gudaspec/plans//structure.md cat gudaspec/research//requirement.md ``` Extract: - Phase结构 - 测试策略Level - 约束集 - 技术决策 ### Step 1: Structure Confirmation ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 计划详细化: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 需求ID: 测试策略: Level 【计划结构回顾】 Phase 1: — Phase 2: — Phase 3: — 接下来我将逐Phase编写详细内容。 每个Phase完成后会请您确认。 准备开始？ ``` ### Step 2: Detail Each Phase (Interactive Loop) **For each Phase:** #### 2.1 Generate Test Specifications (if Level >= 1) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🧪 Phase 1 测试规格 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【测试目标】 验证: 【测试用例】 ┌─────────────────────────────────────────────────────────────┐ │ Test 1: │ ├─────────────────────────────────────────────────────────────┤ │ 场景: │ │ 输入: │ │ 期望: │ │ 验证: │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────┐ │ Test 2: │ ├─────────────────────────────────────────────────────────────┤ │ 场景: │ │ 输入: │ │ 期望: │ │ 验证: │ └─────────────────────────────────────────────────────────────┘ 【测试代码骨架】 ```python # tests/test_.py class TestPhase1: """Phase 1: 测试""" def test_(self): """ 场景: 期望: """ # Arrange # Act # Assert assert , "" def test_(self): """边界情况: """ # TODO: Implement pass ``` 【Property Tests】(if Level 2) ```python from hypothesis import given, strategies as st @given(st.text(min_size=1, max_size=100)) def test_(input_value): """ Property: """ result = (input_value) assert ``` ``` 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 发现】 • ⚠️ → 建议: • ✅ 依赖顺序正确 • ✅ 测试覆盖完整 【Gemini 发现】 • ⚠️ → 建议: • ✅ 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//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