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]

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

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