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]

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:

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