commands/gudaspec/deepresearch.md

name: GudaSpec: Deep Research description: External problem domain research - analyze available technologies, patterns, and best practices. category: GudaSpec tags: [gudaspec, research, external, greenfield, technology] argument-hint: [requirement-id]

CRITICAL: RESEARCH ONLY, NO IMPLEMENTATION

• DO NOT write any implementation code
• DO NOT make final technology decisions without user confirmation
• ONLY gather information, compare options, document constraints
• Present options objectively with pros/cons

Purpose

执行问题域调研（External Research），研究外部技术、模式和最佳实践，为需求实现提供技术选型依据。

Guardrails

• MUST read internal.md first to understand existing constraints
• MANDATORY: Use mcp__grok-search for external research
• MUST verify external recommendations against internal constraints
• All findings must include source URLs
• Prefer recent sources (2024-2025)

---

Steps

Step 0: Load Internal Research

# Read internal research for context
cat gudaspec/research/<requirement-id>/internal.md

Extract:

• Hard constraints (compatibility requirements)
• Existing technology stack
• Integration points
• Open questions that need external research

Step 1: Identify Research Topics

Based on internal research triggers, identify specific research topics:

📋 External Research 议题

需求ID: <requirement-id>
基于内部研究，需要调研以下议题:

| ID | 议题 | 调研目的 | 与内部约束关系 |
|----|------|----------|----------------|
| ER-1 | <topic> | <purpose> | <constraint compatibility> |
| ER-2 | <topic> | <purpose> | <constraint compatibility> |

确认开始调研？

Step 2: Execute External Research

For each research topic, use mcp__grok-search:

Search Patterns:

调研类型	搜索模式
技术对比	"[Tech A] vs [Tech B] [use case] 2024 2025"
最佳实践	"[Domain] best practices production 2025"
实现参考	"[Framework] [feature] implementation example"
API限制	"[Service] API rate limits pricing 2025"
安全考量	"[Technology] security vulnerabilities CVE 2024"

Step 3: Analyze Each Topic

For each topic, gather:

• Multiple options/approaches
• Pros and cons of each
• Compatibility with internal constraints
• Community adoption and maintenance status
• License considerations

Step 4: Generate External Document

Create:

gudaspec/research/<requirement-id>/external.md

Document Template:

---
requirement_id: <requirement-id>
created: <ISO timestamp>
researcher: claude
status: pending-review
type: external
internal_ref: gudaspec/research/<requirement-id>/internal.md
---

# External Research: <Requirement Description>

## 调研背景

### 内部约束回顾
| 约束ID | 约束描述 | 对外部选型的影响 |
|--------|----------|------------------|
| HC-1 | <constraint> | <impact on selection> |
| ... | | |

### 现有技术栈
| 类型 | 技术 | 版本 |
|------|------|------|
| <type> | <tech> | <version> |

---

## 调研议题 1: <Topic Name>

### 调研问题
<What we need to find out>

### 选项分析

#### 选项 A: <Option Name>

| 维度 | 评估 |
|------|------|
| 描述 | |
| 官方文档 | [链接]() |
| GitHub Stars | |
| 最近更新 | |
| License | |

**优势**:
- [ ] <advantage 1> — 确认
- [ ] <advantage 2> — 确认

**劣势**:
- [ ] <disadvantage 1> — 确认
- [ ] <disadvantage 2> — 确认

**与内部约束兼容性**:
| 约束 | 兼容? | 说明 |
|------|-------|------|
| HC-1 | ✅/❌/⚠️ | <explanation> |

**参考实现**:
- [项目名](URL) — <what to learn>

**来源**: [URL1](), [URL2]()

---

#### 选项 B: <Option Name>

<Same structure as Option A>

---

#### 选项对比

| 维度 | 选项 A | 选项 B | 选项 C |
|------|--------|--------|--------|
| 学习曲线 | | | |
| 性能 | | | |
| 社区支持 | | | |
| 与现有栈兼容 | | | |
| 维护成本 | | | |

**初步推荐**: <Option X>
**推荐理由**: <reasoning based on internal constraints>
**确认**: [ ]

---

## 调研议题 2: <Topic Name>

<Same structure as Topic 1>

---

## 最佳实践发现

| ID | 实践 | 来源 | 适用性 | 确认 |
|----|------|------|--------|------|
| BP-1 | <practice> | [URL]() | <applicability> | [ ] |
| BP-2 | <practice> | [URL]() | <applicability> | [ ] |

---

## 外部服务约束

| 服务 | 约束类型 | 限制值 | 对设计影响 | 确认 |
|------|----------|--------|------------|------|
| <service> | Rate Limit | <value> | <impact> | [ ] |
| <service> | Pricing | <value> | <impact> | [ ] |

---

## 安全考量

| ID | 考量 | 风险级别 | 缓解措施 | 确认 |
|----|------|----------|----------|------|
| SEC-1 | <consideration> | 高/中/低 | <mitigation> | [ ] |

---

## 开放问题

| ID | 问题 | 上下文 | 您的回答 |
|----|------|--------|----------|
| OQ-E-1 | | | __________ |
| OQ-E-2 | | | __________ |

---

## 外部约束汇总

### 硬约束 (来自外部研究)
| ID | 约束 | 来源 | 确认 |
|----|------|------|------|
| HC-E-1 | | [URL]() | [ ] |

### 软约束 (来自外部研究)
| ID | 约束 | 来源 | 确认 |
|----|------|------|------|
| SC-E-1 | | [URL]() | [ ] |

---

## 下一步

文档已生成，请执行以下操作：

1. **清空上下文**: 输入 `/clear`
2. **开始审查**: 输入 `/gudaspec:deep-research-review <requirement-id>`

Step 5: Final Output

✅ External Research 完成

需求ID: <requirement-id>
文档位置: gudaspec/research/<requirement-id>/external.md

调研摘要:
- 调研议题: [X] 个
- 技术选项: [Y] 个
- 最佳实践: [Z] 条
- 外部约束: [N] 条
- 开放问题: [M] 个

📋 下一步操作:
1. 输入 /clear 清空当前上下文
2. 输入 /gudaspec:deep-research-review <requirement-id> 开始审查

---

Exit Criteria

• Internal constraints reviewed for compatibility checking
• All research topics investigated
• Multiple options compared for each topic
• Compatibility with internal constraints verified
• External document saved
• User reminded to /clear and proceed to review