commands/gudaspec/research.md

---
name: GudaSpec: Research
description: Internal codebase research - analyze existing code constraints and generate requirement ID.
category: GudaSpec
tags: [gudaspec, research, internal, brownfield, constraints]
---

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

## CRITICAL: DOCUMENT ONLY, NO SUGGESTIONS

- **DO NOT** suggest improvements or changes
- **DO NOT** critique implementation or identify problems
- **DO NOT** recommend refactoring or optimizations
- **ONLY** describe: what exists, where it exists, how components interact
- You are creating a **technical map** of constraints, not a roadmap for changes

## Purpose

执行代码域调研（Internal Research），分析现有代码库约束，生成需求ID和待审查的内部研究文档。

## Guardrails

- If project lacks `./openspec/` directory, prompt user to run `/gudaspec:init`.
- **MANDATORY**: Use `mcp__auggie-mcp__codebase-retrieval` to minimize grep/find operations.
- **NEVER** divide tasks by roles. **ALWAYS** divide by context boundaries.
- Base all judgments on code evidence. Speculation prohibited.
- All findings must include file:line references.

---

## Steps

### Step 0: Receive Requirement

When invoked, respond:

```
我已准备好进行代码域调研。请描述您的需求，我将：

1. 分析现有代码库中的相关约束
2. 生成需求ID便于后续管理
3. 输出待审查的内部研究文档

请描述您的需求：
```

Wait for user input.

### Step 1: Generate Requirement ID

Based on user's requirement description, generate a kebab-case ID:

**命名规范**（参考OpenSpec）：
- 格式: `<action>-<target>[-<scope>]`
- 动作词: `add`, `fix`, `update`, `remove`, `refactor`, `migrate`
- 全小写，单词间用连字符
- 长度: 3-5个单词
- 避免缩写，保持可读性

**示例**：
| 用户需求 | 生成的需求ID |
|----------|--------------|
| "添加Outlook邮件前端" | `add-outlook-email-frontend` |
| "修复用户登录超时问题" | `fix-user-login-timeout` |
| "重构支付模块" | `refactor-payment-module` |
| "添加双因素认证" | `add-two-factor-auth` |
| "迁移数据库到PostgreSQL" | `migrate-database-postgresql` |

Confirm with user:
```
需求ID: <generated-id>
确认此ID或提供修改建议：
```

### Step 2: Read Mentioned Files

- If user mentions specific files, read them **FULLY** before proceeding
- This ensures complete context before decomposition

### Step 3: Codebase Assessment

Use `mcp__auggie-mcp__codebase-retrieval` to:
- Scan project structure
- Identify relevant modules/directories
- Determine context boundaries for parallel research

### Step 4: Define Context Boundaries

Divide by **context**, not roles:

| Correct (Context) | Incorrect (Role) |
|-------------------|------------------|
| User-related code | "架构师 agent" |
| Authentication layer | "安全专家 agent" |
| Data access layer | "DBA agent" |
| Target feature area | "领域专家 agent" |

### Step 5: Parallel Subagent Research

For each context boundary, spawn subagent:

```
You are a documentarian, NOT a critic.
Document what EXISTS, not what SHOULD BE.

Context: [boundary_name]
Scope: [directories/files]

Output JSON:
{
  "context_boundary": "string",
  "relevant_files": [{"path": "", "purpose": "", "key_exports": [], "lines": ""}],
  "existing_patterns": ["pattern - location"],
  "hard_constraints": ["constraint - file:line - reason"],
  "soft_constraints": ["convention - where observed"],
  "dependencies": {"internal": [], "external": []},
  "information_flow": "description",
  "integration_points": ["where new code must connect"],
  "open_questions": ["question - context"]
}
```

### Step 6: Aggregate and Generate Internal Document

Create directory and file:
```
gudaspec/research/<requirement-id>/internal.md
```

**Document Template**:

````markdown
---
requirement_id: <requirement-id>
created: <ISO timestamp>
researcher: claude
git_commit: <current commit>
branch: <current branch>
status: pending-review
type: internal
---

# Internal Research: <Requirement Description>

## 需求概述
<用户原始需求描述 - 完整记录>

## 代码库概况

### 项目结构
```
<relevant directory tree>
```

### 技术栈
| 类型 | 技术 | 版本 | 配置位置 |
|------|------|------|----------|
| 框架 | | | |
| 数据库 | | | |
| ... | | | |

---

## 约束发现

### 硬约束 (CANNOT violate)

> 以下约束必须严格遵守，违反将导致系统故障或不兼容

| ID | 约束描述 | 来源 | 原因 | 确认 |
|----|----------|------|------|------|
| HC-1 | | `file:line` | | [ ] |
| HC-2 | | `file:line` | | [ ] |
| HC-3 | | `file:line` | | [ ] |

### 软约束 (SHOULD follow)

> 以下为项目惯例，建议遵循以保持一致性

| ID | 约束描述 | 观察位置 | 灵活度 | 确认 |
|----|----------|----------|--------|------|
| SC-1 | | | | [ ] |
| SC-2 | | | | [ ] |

---

## 相关文件分析

### 核心文件

| 文件路径 | 用途 | 关键导出 | 与需求关系 | 确认 |
|----------|------|----------|------------|------|
| | | | | [ ] |
| | | | | [ ] |

### 信息流

```
<ASCII diagram showing data flow relevant to requirement>
```

确认信息流准确: [ ]

---

## 集成点

> 新代码需要与以下位置对接

| ID | 集成位置 | 文件 | 对接方式 | 确认 |
|----|----------|------|----------|------|
| IP-1 | | | | [ ] |
| IP-2 | | | | [ ] |

---

## 依赖关系

### 内部依赖
| 模块 | 依赖 | 关系类型 | 确认 |
|------|------|----------|------|
| | | | [ ] |

### 外部依赖
| 包名 | 版本 | 用途 | 确认 |
|------|------|------|------|
| | | | [ ] |

---

## 现有测试

| 测试文件 | 覆盖范围 | 状态 | 与需求相关 | 确认 |
|----------|----------|------|------------|------|
| | | | | [ ] |

---

## 开放问题

> 以下问题需要您的确认

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

---

## External Research 初步判断

基于以上内部研究，以下情况可能需要外部调研：

| 触发条件 | 检测结果 | 说明 |
|----------|----------|------|
| 引入新技术/库 | ⬜ 是 / ⬜ 否 | |
| 代码库无相关参考 | ⬜ 是 / ⬜ 否 | |
| 新架构模式 | ⬜ 是 / ⬜ 否 | |
| 未知领域知识 | ⬜ 是 / ⬜ 否 | |
| 用户显式要求 | ⬜ 是 / ⬜ 否 | |

初步建议: [ ] 需要 External Research / [ ] 不需要
````

### Step 7: Final Output

```
✅ Internal Research 完成

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

发现摘要:
- 硬约束: [X] 条
- 软约束: [Y] 条
- 集成点: [Z] 处
- 开放问题: [N] 个

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

---

## Exit Criteria

- [ ] Requirement ID generated and confirmed
- [ ] All context boundaries explored
- [ ] Internal document saved to `gudaspec/research/<id>/internal.md`
- [ ] All checkboxes initialized as unchecked
- [ ] User reminded to `/clear` and proceed to review

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