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]
---

<!-- GUDASPEC:DEEPRESEARCH:START -->

## 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

```bash
# 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**:

```markdown
---
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

<!-- GUDASPEC:DEEPRESEARCH:END -->