commands/gudaspec/plan.md

name: GudaSpec: Plan description: Analyze requirements and design implementation plan structure with test strategy selection. category: GudaSpec tags: [gudaspec, plan, structure, multi-model, tdd] argument-hint: [requirement.md path]

Purpose

分析需求文档，设计计划结构，选择测试策略。产出计划结构草案供review阶段确认和细化。

Core Principles

1. Read Everything First — 完整读取所有引用文件后再分析
2. Verify Before Plan — 验证约束仍然有效
3. Structure Before Detail — 先确认结构，再写细节
4. Test Strategy Early — 在结构阶段就决定测试策略

Guardrails

• If project lacks gudaspec/ directory, prompt user to run /gudaspec:init.
• MUST read requirement.md and ALL referenced files completely.
• MUST verify constraints against current codebase.
• MUST get user confirmation on plan structure before proceeding.
• NEVER write detailed implementation steps in this phase.
• Keep context under 50K tokens.

---

Steps

Step 0: Load Requirement Document

With parameter:

/gudaspec:plan gudaspec/research/<requirement-id>/requirement.md

Read the file and all files mentioned in it.

Without parameter:

请提供需求文档路径:
/gudaspec:plan gudaspec/research/<requirement-id>/requirement.md

Step 1: Context Gathering & Verification

1. Extract from requirement.md:

   • 约束集（硬约束 + 软约束）
   • 技术决策
   • 集成点
   • 成功标准
   • 实施边界

2. Read all referenced source files

3. Verify constraints still valid:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 约束验证
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| 约束ID | 状态 | 说明 |
|--------|------|------|
| HC-I-1 | ✅ 有效 | 代码未变更 |
| HC-I-2 | ⚠️ 变化 | 文件已移动到新位置 |
| SC-E-1 | ✅ 有效 | 外部API仍适用 |

4. Present understanding for confirmation

Use AskUserQuestions to confirm understanding.

Step 2: Multi-Model Analysis

Invoke mcp__codex__codex:

Analyze this requirement for implementation planning:
[paste key constraints and decisions]

Identify:
1. Implementation risks
2. Dependency order between components
3. Edge cases to address
4. Suggested phase boundaries

Invoke mcp__gemini__gemini:

Analyze this requirement for implementation planning:
[paste key constraints and decisions]

Identify:
1. UI/UX implementation considerations
2. Component structure recommendations
3. State management implications
4. Testing challenges for frontend

Present synthesized findings:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 多模型分析结果
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【风险识别】
• <risk 1>
• <risk 2>

【依赖顺序建议】
1. <first>
2. <second>
3. <third>

【建议的Phase边界】
• Phase 1 与 Phase 2 在 <component> 处分界
• 原因: <rationale>

Step 3: Test Strategy Selection

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧪 测试策略选择
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

请选择本次实施的测试策略:

┌─────────────────────────────────────────────────────────────┐
│ Level 0: 标准验证模式                                        │
├─────────────────────────────────────────────────────────────┤
│ • 使用Success Criteria命令验证                              │
│ • 不生成测试代码                                            │
│ • 适合: 简单修复、配置变更、原型探索                        │
│ • 验证方式: 运行现有测试 + 手动检查                         │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Level 1: TDD模式 ⭐推荐                                      │
├─────────────────────────────────────────────────────────────┤
│ • 先写测试，再写实现 (Red-Green-Refactor)                   │
│ • 生成测试骨架代码                                          │
│ • 适合: 标准功能开发、API开发、业务逻辑                     │
│ • 验证方式: 测试从红变绿 + 手动检查                         │
│                                                              │
│ 【TDD如何帮助AI开发】                                        │
│ • 失败测试为AI提供精确的任务定义                            │
│ • 防止AI"幻觉"——测试会立即暴露错误                         │
│ • 每个小步骤都有验证，错误不会累积                          │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Level 2: TDD + Property Testing                              │
├─────────────────────────────────────────────────────────────┤
│ • 包含Level 1全部内容                                        │
│ • 额外定义Property不变量                                     │
│ • 随机输入发现边界情况                                       │
│ • 适合: 关键业务逻辑、安全功能、数据处理                    │
│ • 验证方式: 测试通过 + Property验证 + 手动检查              │
│                                                              │
│ 【Property Testing示例】                                     │
│ • "密码永不出现在日志中" — 随机测试1000种输入               │
│ • "加密后解密等于原文" — 验证往返一致性                     │
└─────────────────────────────────────────────────────────────┘

基于您的需求特点，我建议: Level <X>
原因: <rationale>

Use AskUserQuestions:

question: "选择测试策略Level"
options: [
  "Level 0: 标准验证（简单任务）",
  "Level 1: TDD模式（推荐）",
  "Level 2: TDD + Property Testing（关键逻辑）",
  "不确定，请解释更多"
]

Step 4: Design Plan Structure

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📐 计划结构设计
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【实施策略概述】
<1-2句话描述整体策略>

【Phase划分】

┌─────────────────────────────────────────────────────────────┐
│ Phase 1: <名称>                                              │
├─────────────────────────────────────────────────────────────┤
│ 目标: <完成什么>                                            │
│ 涉及: <模块/文件范围>                                       │
│ 依赖: 无                                                    │
│ 预计: ~<N>个文件变更                                        │
│ 测试: <Level对应的验证方式>                                 │
└─────────────────────────────────────────────────────────────┘
       │
       │ 完成 + 验证通过
       ▼
┌─────────────────────────────────────────────────────────────┐
│ Phase 2: <名称>                                              │
├─────────────────────────────────────────────────────────────┤
│ 目标: <完成什么>                                            │
│ 涉及: <模块/文件范围>                                       │
│ 依赖: Phase 1                                               │
│ 预计: ~<N>个文件变更                                        │
│ 测试: <Level对应的验证方式>                                 │
└─────────────────────────────────────────────────────────────┘
       │
       │ 完成 + 验证通过
       ▼
┌─────────────────────────────────────────────────────────────┐
│ Phase 3: <名称>                                              │
├─────────────────────────────────────────────────────────────┤
│ 目标: <完成什么>                                            │
│ 涉及: <模块/文件范围>                                       │
│ 依赖: Phase 2                                               │
│ 预计: ~<N>个文件变更                                        │
│ 测试: <Level对应的验证方式>                                 │
└─────────────────────────────────────────────────────────────┘

【明确不包含】
• ❌ <排除项1> — 原因: <reason>
• ❌ <排除项2> — 原因: <reason>

【风险预判】
| 风险 | 严重度 | 缓解策略 |
|------|--------|----------|
| <risk> | 高/中/低 | <mitigation> |

Use AskUserQuestions:

question: "计划结构是否合适？"
options: [
  "合适，保存并继续",
  "需要调整Phase划分",
  "需要调整范围边界",
  "风险评估需要修改"
]

Step 5: Save Structure Document

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

---
requirement_id: <requirement-id>
created: <ISO timestamp>
planner: claude
status: structure-approved
test_level: <0|1|2>
requirement_ref: gudaspec/research/<requirement-id>/requirement.md
git_commit: <current commit>
branch: <current branch>
---

# Plan Structure: <Requirement Title>

## 实施策略
<strategy overview>

## 约束验证结果
| 约束ID | 状态 | 说明 |
|--------|------|------|
...

## 多模型分析摘要
### 风险
...
### 依赖顺序
...

## 测试策略
Level: <0|1|2>
原因: <rationale>

## Phase结构

### Phase 1: <name>
- 目标: 
- 涉及: 
- 依赖: 
- 预计变更: 

### Phase 2: <name>
...

## 不包含
- ❌ ...

## 风险预判
| 风险 | 严重度 | 缓解策略 |
...

## 下一步
/clear → /gudaspec:plan-review <requirement-id>

Step 6: Completion Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 计划结构已保存
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

需求ID: <requirement-id>
结构文档: gudaspec/plans/<requirement-id>/structure.md

结构摘要:
┌─────────────────────────────────────────┐
│ Phase数量: [N]                          │
│ 测试策略: Level [X]                     │
│ 预计文件变更: [Y] 个                    │
│ 风险等级: 高/中/低                      │
└─────────────────────────────────────────┘

📋 下一步操作:
1. 输入 /clear 清空当前上下文
2. 输入 /gudaspec:plan-review <requirement-id>

plan-review阶段将:
• 确认每个Phase的详细内容
• 生成具体的代码变更说明
• 生成测试规格（Level 1-2）
• 最终批准计划

---

Exit Criteria

• Requirement document fully read and understood
• All referenced files read
• Constraints verified against current code
• Multi-model analysis completed
• Test strategy level selected
• Plan structure designed and approved
• Structure document saved
• User directed to /gudaspec:plan-review