commands/gudaspec/research-review.md

---
name: GudaSpec: Research Review
description: Interactive review of internal research - user-friendly confirmation through guided questions.
category: GudaSpec
tags: [gudaspec, research, review, internal, interactive]
argument-hint: [requirement-id]
---

<!-- GUDASPEC:RESEARCH-REVIEW:START -->

## Purpose

以用户友好的方式审查内部研究发现。通过场景化描述和引导式问题，帮助用户理解并确认约束，无需深入技术细节。

## Core Principles

1. **场景驱动**：将技术约束转化为用户场景
2. **选择优先**：尽量提供选项而非开放式问题
3. **关联解释**：说明每个决策对后续的影响
4. **渐进深入**：先确认大方向，再处理细节
5. **智能分组**：将相关约束串联成有意义的主题

## Guardrails

- **MUST** use `AskUserQuestions` tool for all confirmations
- **MUST** translate technical constraints into user-understandable language
- **MUST** explain WHY each confirmation matters
- **NEVER** dump raw technical details without context
- **NEVER** ask users to confirm things they cannot reasonably evaluate

---

## Steps

### Step 0: Load and Analyze Internal Document

```bash
cat gudaspec/research/<requirement-id>/internal.md
```

After loading, perform **Constraint Clustering**:
- Group related constraints by theme/scenario
- Identify dependencies between constraints
- Rank by importance (blocking vs nice-to-have)
- Prepare user-friendly translations

### Step 1: Welcome and Context Setting

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 需求审查: <Requirement Description>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

需求ID: <requirement-id>

我已完成代码库分析，发现了一些需要您确认的关键点。
接下来我会通过几个简单的问题来确认这些发现。

📊 审查概览:
┌─────────────────────────────────────┐
│ 核心场景确认    ████████░░  3 个    │
│ 技术适配确认    ██████░░░░  2 个    │
│ 实施边界确认    ████░░░░░░  1 个    │
│ 开放问题        ██░░░░░░░░  2 个    │
└─────────────────────────────────────┘

预计用时: 5-10 分钟

准备好开始了吗？
```

Use `AskUserQuestions`:
```
options: ["开始审查", "先看一下完整的研究文档"]
```

---

### Step 2: Core Scenario Confirmation (场景化约束确认)

**Strategy**: Group related constraints into user scenarios, ask about the scenario rather than individual constraints.

**Example Transformation**:

| 原始约束 (技术) | 转化后 (场景) |
|-----------------|---------------|
| HC-1: 密码必须bcrypt, cost=12 | |
| HC-2: 登录失败5次锁定30分钟 | → "用户登录安全" 场景 |
| HC-3: JWT用HS256算法 | |
| SC-1: 错误响应用RFC 7807格式 | |

**Scenario Presentation Format**:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔐 场景 1/3: 用户登录安全
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

我发现项目中已有一套完整的登录安全机制：

【当前实现方式】
• 密码存储：使用 bcrypt 加密（业界推荐的安全方案）
• 防暴力破解：连续失败 5 次后锁定账户 30 分钟
• 登录凭证：使用 JWT Token，15分钟过期

【这意味着什么】
您的新功能需要 [复用/适配/绕开] 这套机制。
如果您的功能涉及用户身份验证，必须走这套流程。

【对您需求的影响】
<根据具体需求说明影响，例如>
- 如果需要新增登录方式，需要集成到现有的 AuthService
- 如果需要延长登录时间，需要调整 JWT 配置
```

Use `AskUserQuestions`:
```
question: "您的需求与用户登录安全的关系是？"
options: [
  "需要复用现有登录机制（如：新增OAuth登录方式）",
  "需要修改现有机制（如：调整锁定策略）", 
  "与登录无关，可以跳过",
  "不确定，需要更多解释"
]
```

**If user selects "不确定"**, provide deeper explanation:
```
让我举个具体例子：

假设您要添加"Outlook邮件集成"功能：
- 如果用户需要登录才能使用邮件功能 → 复用现有机制
- 如果Outlook需要单独的OAuth认证 → 可能需要扩展机制
- 如果只是后台同步邮件，用户无感知 → 与登录无关

您的需求更接近哪种情况？
```

**Record Decision**: Update internal.md with user's choice and rationale.

---

### Step 3: Technical Adaptation Confirmation (技术适配确认)

**Strategy**: Present technical constraints as "project rules" that need to be followed, ask if there are special reasons to deviate.

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔧 技术适配: 项目规范
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

我发现项目遵循以下规范，新代码应保持一致：

【代码风格】
┌────────────────────────────────────────────┐
│ 📁 目录结构: src/<模块>/[router|service|models].py
│ 📝 命名规范: 函数用 snake_case, 类用 PascalCase
│ 🧪 测试要求: 每个模块需要对应的 tests/<模块>/ 目录
│ 📦 依赖管理: 使用 pyproject.toml + poetry
└────────────────────────────────────────────┘

【API规范】
┌────────────────────────────────────────────┐
│ 🔗 路由风格: RESTful (如 /users/{id}/emails)
│ 📄 响应格式: 统一的 JSON 结构
│ ❌ 错误处理: 使用项目自定义的 AppException
└────────────────────────────────────────────┘

【为什么这很重要】
遵循这些规范可以：
• 让代码更容易被团队其他成员理解
• 复用现有的工具函数和中间件
• 保持项目整体一致性
```

Use `AskUserQuestions`:
```
question: "关于项目规范，请确认："
options: [
  "遵循以上所有规范（推荐）",
  "大部分遵循，但有特殊情况需要说明",
  "这是一个独立模块，可能需要不同的规范"
]
```

**If user selects special case**, follow up:
```
请告诉我特殊情况：
• 哪些规范可能需要调整？
• 调整的原因是什么？
```

---

### Step 4: Integration Points Confirmation (集成点确认)

**Strategy**: Visualize where new code connects to existing code, confirm the connection points.

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔌 集成点: 新代码如何接入现有系统
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

根据您的需求，新功能需要在以下位置与现有代码对接：

```
现有系统                        您的新功能
─────────                      ─────────
                               
┌─────────────┐               ┌─────────────┐
│   用户模块   │◄─────────────│  Outlook    │
│  users/     │   获取用户    │  集成模块   │
└─────────────┘   信息        └─────────────┘
       │                             │
       │                             │
       ▼                             ▼
┌─────────────┐               ┌─────────────┐
│  认证模块   │◄─────────────│  OAuth      │
│  auth/      │   复用认证    │  处理       │
└─────────────┘               └─────────────┘
```

【具体对接点】

1️⃣ 用户信息获取
   位置: src/users/service.py → UserService.get_by_id()
   用途: 获取用户邮箱配置
   
2️⃣ 认证复用
   位置: src/auth/deps.py → get_current_user()
   用途: 验证用户身份

【这意味着什么】
• 您的代码需要导入并调用这些现有函数
• 如果这些函数不满足需求，可能需要扩展（而非重写）
```

Use `AskUserQuestions`:
```
question: "这些集成点是否符合您的预期？"
options: [
  "符合，按此方案集成",
  "基本符合，但可能还需要其他集成点",
  "不太确定，能否解释一下替代方案？"
]
```

---

### Step 5: Scope Boundary Confirmation (边界确认)

**Strategy**: Clearly state what IS and IS NOT included, get explicit confirmation.

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📐 实施边界: 明确范围
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

根据我的分析，本次实施的范围建议如下：

【✅ 包含在内】
• <功能点1>
• <功能点2>
• <功能点3>

【❌ 不包含（建议后续处理）】
• <排除项1> — 原因: <简要说明>
• <排除项2> — 原因: <简要说明>

【⚠️ 需要您决定】
• <边界模糊项> — 包含它会增加约 X 天工作量
```

Use `AskUserQuestions`:
```
question: "关于实施边界："
options: [
  "同意以上边界划分",
  "需要包含更多功能（请说明）",
  "范围太大，需要进一步缩减"
]
```

---

### Step 6: Open Questions (开放问题 - 智能提问)

**Strategy**: Transform technical open questions into business decisions with clear options.

**Example Transformation**:

| 原始问题 (技术) | 转化后 (业务决策) |
|-----------------|-------------------|
| "JWT TTL 设置多少？" | "用户需要多久重新登录一次？" |
| "是否需要 rate limiting？" | "如何防止用户过于频繁调用？" |
| "缓存策略用什么？" | "数据实时性要求高吗？" |

**Presentation Format**:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❓ 需要您决定: 邮件同步频率
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【背景】
Outlook邮件集成需要定期从服务器获取新邮件。
同步频率会影响：
• 实时性：频率越高，用户越快看到新邮件
• 成本：频率越高，API调用次数越多
• 性能：频率越高，服务器负载越大

【选项对比】
┌─────────────────────────────────────────────┐
│ 选项         │ 延迟    │ API成本 │ 适用场景 │
├─────────────────────────────────────────────┤
│ A. 实时推送  │ < 1秒  │ 高      │ 即时通讯 │
│ B. 每5分钟   │ ≤ 5分钟│ 中      │ 一般办公 │
│ C. 每30分钟  │ ≤ 30分钟│ 低     │ 非紧急   │
│ D. 手动刷新  │ 用户控制│ 最低   │ 低频使用 │
└─────────────────────────────────────────────┘
```

Use `AskUserQuestions`:
```
question: "邮件同步频率选择哪个方案？"
options: ["A. 实时推送", "B. 每5分钟（推荐）", "C. 每30分钟", "D. 手动刷新", "需要更多信息来决定"]
```

---

### Step 7: External Research Determination (智能判断)

**Strategy**: Don't just ask "need external research?", explain what would be researched and why.

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 是否需要外部调研？
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

基于以上讨论，我识别到以下可能需要外部调研的点：

【需要调研的内容】
┌─────────────────────────────────────────────┐
│ 1. Microsoft Graph API vs EWS              │
│    原因: 项目中没有Outlook集成先例         │
│    影响: 决定整体技术架构                  │
│    调研内容: API能力对比、认证方式、限制   │
├─────────────────────────────────────────────┤
│ 2. OAuth 2.0 最佳实践                      │
│    原因: 现有OAuth实现仅支持Google         │
│    影响: Token管理和刷新策略               │
│    调研内容: Microsoft OAuth流程差异       │
└─────────────────────────────────────────────┘

【如果跳过外部调研】
• 我将基于通用知识进行实施
• 可能无法选择最优方案
• 后续可能需要返工

【如果进行外部调研】
• 预计额外需要 1 轮对话
• 将获得针对性的技术选型建议
• 降低实施风险
```

Use `AskUserQuestions`:
```
question: "是否进行外部调研？"
options: [
  "是，进行调研（推荐：涉及新技术）",
  "否，我对技术选型已有明确想法",
  "否，这是简单需求，不需要调研"
]
```

**If user skips and has clear idea**, follow up:
```
您提到已有明确想法，请告诉我：
• 您倾向使用什么技术方案？
• 有什么特殊考虑因素吗？
```

---

### Step 8: Summary and Confirmation (总结确认)

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 审查总结
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

感谢您的耐心确认！以下是本次审查的结果：

【您的关键决策】
┌─────────────────────────────────────────────┐
│ 1. 登录安全: 复用现有机制                  │
│ 2. 项目规范: 完全遵循                      │
│ 3. 集成方案: 按建议的3个点对接            │
│ 4. 实施边界: 同意建议范围                  │
│ 5. 同步频率: 每5分钟                       │
│ 6. 外部调研: 需要                          │
└─────────────────────────────────────────────┘

【这些决策的影响】
• 实施复杂度: 中等
• 预计涉及文件: 8-12 个
• 需要新增依赖: 2 个 (msgraph-sdk, msal)

【下一步】
<根据是否需要外部调研显示不同内容>
```

Use `AskUserQuestions`:
```
question: "以上总结是否准确？"
options: [
  "准确，继续下一步",
  "需要修改某项决策",
  "需要补充说明"
]
```

---

### Step 9: Output and Next Steps

**If External Research Needed**:
```
✅ Internal Research 审查完成

需求ID: <requirement-id>
审查状态: 已确认，待外部调研

📋 下一步操作:
1. 输入 /clear 清空当前上下文
2. 输入 /gudaspec:deepresearch <requirement-id> 开始外部调研

外部调研将解答:
• Microsoft Graph API 技术选型
• OAuth 2.0 集成方案
```

**If No External Research Needed**:
```
✅ Research 全部完成

需求ID: <requirement-id>
最终需求文档: gudaspec/research/<requirement-id>/requirement.md

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

---

## Question Design Patterns (问题设计模式)

### Pattern 1: Scenario-Based (场景式)
```
【场景描述】
当用户执行 <动作> 时，系统当前会 <行为>。

【问题】
您的需求是否需要改变这个行为？
```

### Pattern 2: Impact-Driven (影响驱动)
```
【发现】
项目使用 <技术/模式>。

【如果遵循】<好处>
【如果偏离】<代价>

【问题】
您希望如何处理？
```

### Pattern 3: Trade-off (权衡式)
```
【权衡点】
<选项A> vs <选项B>

【A的特点】<优劣>
【B的特点】<优劣>

【问题】
哪个更符合您的需求？
```

### Pattern 4: Clarification (澄清式)
```
【我的理解】
您希望实现 <功能描述>

【确认点】
- <细节1>: 是这样吗？
- <细节2>: 还是这样？

【问题】
我的理解正确吗？
```

---

## Exit Criteria

- [ ] All scenarios confirmed via interactive questions
- [ ] All user decisions recorded with rationale
- [ ] External research need determined with clear reasoning
- [ ] User explicitly confirmed summary
- [ ] Document updated with confirmed decisions
- [ ] User directed to appropriate next step

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