requirements

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Requirements Gathering

需求收集

This skill covers a structured 5-phase requirements gathering workflow for new features. It guides you through initial setup and codebase analysis, context discovery questions, autonomous context gathering, expert requirements questions, and final requirements documentation — producing a comprehensive spec ready for implementation.

本Skill涵盖一套用于新功能的结构化5阶段需求收集工作流。它会引导你完成初始设置与代码库分析、上下文探索提问、自主上下文收集、专业需求提问，以及最终需求文档输出的全流程，最终生成可直接用于开发的完整规格说明。

Start Workflow

启动工作流

Begin gathering requirements for a new feature using this structured 5-phase process.

使用这套结构化的5阶段流程开始收集新功能的需求。

Phase 1: Initial Setup & Codebase Analysis

阶段1：初始设置与代码库分析

Get current timestamp:
```
`date "+%Y-%m-%d-%H%M"`
```
Extract slug from the feature description (e.g., "add user profile" -> "user-profile")
Create folder:
```
requirements/[timestamp]-[slug]/
```
Create initial files:
- ```
00-initial-request.md
```
  with the user's request
- ```
metadata.json
```
  with status tracking
Create/update
```
requirements/.current-requirement
```
with folder name
Analyze project codebase structure:
- ```
apps/web-app/
```
  - TanStack Start frontend + TRPC server
- ```
packages/
```
  - Shared packages (db, services, common, logger, agents)
- Identify relevant existing features and patterns

获取当前时间戳：
```
`date "+%Y-%m-%d-%H%M"`
```
从功能描述中提取标识（例如："add user profile" -> "user-profile"）
创建文件夹：
```
requirements/[timestamp]-[slug]/
```
创建初始文件：
- ```
00-initial-request.md
```
  存储用户的原始需求
- ```
metadata.json
```
  用于状态跟踪
创建/更新
```
requirements/.current-requirement
```
写入文件夹名称
分析项目代码库结构：
- ```
apps/web-app/
```
  - TanStack Start 前端 + TRPC 服务端
- ```
packages/
```
  - 共享包（db、services、common、logger、agents）
- 识别相关的现有功能和开发规范

Phase 2: Context Discovery Questions

阶段2：上下文探索提问

Generate 5 yes/no questions to understand the problem space.

Focus areas for the project:

User interactions and workflows
Organization/project scope (org-scoped vs user-scoped)
Data model requirements (new tables vs extending existing)
UI requirements (new pages vs extending existing)
Integration with existing features (auth, billing, integrations)

Question format:

markdown

undefined

生成5个是非问题来明确问题范围。

项目聚焦维度：

用户交互与工作流
组织/项目范围（组织级还是用户级）
数据模型需求（新建表还是扩展现有表）
UI需求（新建页面还是扩展现有页面）
与现有功能的集成（鉴权、计费、其他集成能力）

问题格式：

markdown

undefined

Q1: Will this feature be organization-scoped (vs user-scoped)?

Q1: 该功能是否为组织级（而非用户级）功能？

Default if unknown: Yes (most project features are org-scoped)

未知时默认值： 是（多数项目功能都是组织级）

Q2: Will users interact with this through a new page/route?

Q2: 用户是否需要通过新页面/路由访问该功能？

Default if unknown: Yes (most features have dedicated UI)

未知时默认值： 是（多数功能都有独立UI）

Q3: Does this require new database tables?

Q3: 是否需要新建数据库表？

Default if unknown: No (prefer extending existing schema)

未知时默认值： 否（优先扩展现有Schema）

Q4: Will this integrate with external services/APIs?

Q4: 是否需要对接外部服务/API？

Default if unknown: No (unless explicitly mentioned)

未知时默认值： 否（除非明确提及）

Q5: Should this be accessible to all org members or only admins?

Q5: 该功能是否对所有组织成员开放，还是仅管理员可用？

Default if unknown: All members (with appropriate role checks)


**Process:**

1. Write ALL questions to `01-discovery-questions.md` with smart defaults
2. Ask questions ONE at a time, proposing default
3. Accept: yes / no / idk (use default)
4. After ALL answered, record in `02-discovery-answers.md`
5. Update `metadata.json`

未知时默认值： 所有成员（配合适当的角色校验）


**流程：**

1. 将所有问题连同智能默认值写入 `01-discovery-questions.md`
2. 每次仅提出1个问题，同时给出默认值
3. 接收答案：是 / 否 / 不知道（使用默认值）
4. 所有问题回答完毕后，将答案记录到 `02-discovery-answers.md`
5. 更新 `metadata.json`

Phase 3: Targeted Context Gathering (Autonomous)

阶段3：定向上下文收集（自主执行）

After discovery questions answered:

Search relevant code using available tools:
- Find similar features in
```
apps/web-app/src/
```
- Check existing TRPC routers in
```
apps/web-app/src/*/trpc/
```
- Review database schema in
```
packages/db/src/schema.ts
```
- Check existing UI patterns in
```
apps/web-app/src/shared/
```
Analyze patterns from similar features:
- How similar TRPC routers are structured
- How similar pages use TanStack Router loaders
- Database table conventions
- Form handling patterns

Document findings in

03-context-findings.md

markdown

## Codebase Analysis

### Similar Features Found

- [Feature name] at [path] - [why relevant]

### Relevant Files to Modify/Extend

- `apps/web-app/src/[module]/trpc/[router].ts` - [what to add]
- `packages/db/src/schema.ts` - [new tables if needed]

### Patterns to Follow

- TRPC router pattern from [example]
- TanStack route pattern from [example]
- Form pattern from [example]

### Technical Constraints

- [Any limitations discovered]

### Integration Points

- [Services/modules this will interact with]

探索问题全部回答完毕后：

使用可用工具搜索相关代码：
- 在
```
apps/web-app/src/
```
  中查找相似功能
- 检查
```
apps/web-app/src/*/trpc/
```
  中的现有TRPC路由
- 查看
```
packages/db/src/schema.ts
```
  中的数据库Schema
- 查看
```
apps/web-app/src/shared/
```
  中的现有UI规范
分析相似功能的实现模式：
- 相似TRPC路由的结构
- 相似页面如何使用TanStack Router加载器
- 数据库表命名规范
- 表单处理模式

将发现结果写入
03-context-findings.md
：

markdown

## 代码库分析

### 找到的相似功能

- [功能名称] 位于 [路径] - [相关原因]

### 需要修改/扩展的相关文件

- `apps/web-app/src/[模块]/trpc/[路由].ts` - [需要新增的内容]
- `packages/db/src/schema.ts` - [如果需要的话新增的表]

### 需要遵循的规范

- 参考[示例]的TRPC路由模式
- 参考[示例]的TanStack路由模式
- 参考[示例]的表单模式

### 技术约束

- [发现的所有限制]

### 集成点

- [该功能需要交互的服务/模块]

Phase 4: Expert Requirements Questions

阶段4：专业需求提问

Now ask questions like a senior developer who knows the project codebase.

Focus on clarifying system behavior:

markdown

undefined

现在以熟悉项目代码库的高级开发者身份提问。

聚焦于明确系统行为：

markdown

undefined

Q1: Should we extend the existing [Router]Router at [path]?

Q1: 是否需要扩展[路径]下的现有[Router]Router？

Default if unknown: Yes (maintains consistency)

未知时默认值： 是（保持一致性）

Q2: For the UI, should we follow the pattern from [similar feature]?

Q2: UI层面是否需要遵循[相似功能]的模式？

Default if unknown: Yes (established pattern)

未知时默认值： 是（沿用已验证的模式）

Q3: Should this data be cached in TanStack Query or fetched fresh?

Q3: 数据是否需要缓存到TanStack Query，还是每次都重新获取？

Default if unknown: Cached (standard for most data)

未知时默认值： 缓存（多数数据的标准处理方式）

Q4: Should we add E2E tests for this flow?

Q4: 是否需要为该流程添加E2E测试？

Default if unknown: Yes (if user-facing feature)

未知时默认值： 是（如果是面向用户的功能）

Q5: Should validation happen client-side, server-side, or both?

Q5: 校验应该放在客户端、服务端还是两端都做？

Default if unknown: Both (Zod on frontend, TRPC input validation on backend)


**Process:**

1. Write questions to `04-detail-questions.md`
2. Ask ONE at a time
3. Record answers in `05-detail-answers.md` after all asked

未知时默认值： 两端都做（前端用Zod，后端用TRPC输入校验）


**流程：**

1. 将问题写入 `04-detail-questions.md`
2. 每次仅提出1个问题
3. 所有问题回答完毕后，将答案记录到 `05-detail-answers.md`

Phase 5: Requirements Documentation

阶段5：需求文档生成

Generate comprehensive spec in

06-requirements-spec.md

markdown

undefined

在

06-requirements-spec.md

中生成完整的规格说明：

markdown

undefined

Requirements Specification: [Name]

需求规格说明：[名称]

Generated: [timestamp] Status: Complete

生成时间：[timestamp] 状态：已完成

Overview

概述

[Problem statement and solution summary]

[问题陈述与解决方案摘要]

Functional Requirements

功能需求

User Stories

用户故事

As a [role], I want to [action] so that [benefit]

作为[角色]，我想要[操作]，以便[收益]

Acceptance Criteria

验收标准

[Testable criterion]

[可测试的验收条件]

Technical Requirements

技术需求

Database Changes

数据库变更

New table: [name] in
```
packages/db/src/schema.ts
```
Fields: [list with types]

新表：
```
packages/db/src/schema.ts
```
中的[表名]
字段：[带类型的字段列表]

TRPC Router

TRPC路由

Location:

apps/web-app/src/[module]/trpc/[name].ts

Procedures: [list]
Use
```
protectedMemberAccessProcedure
```
for org-scoped operations

位置：

apps/web-app/src/[模块]/trpc/[名称].ts

接口：[列表]
组织级操作使用
```
protectedMemberAccessProcedure
```

Frontend Routes

前端路由

New route:
```
/app/[path]
```
Components: [list]
Pattern to follow: [reference]

新路由：
```
/app/[路径]
```
组件：[列表]
遵循模式：[参考]

Files to Create/Modify

需要创建/修改的文件

```
packages/db/src/schema.ts
```
- Add table

apps/web-app/src/[module]/trpc/[name].ts

- Add router

apps/web-app/src/routes/app/[path]/route.tsx

- Add page

```
packages/db/src/schema.ts
```
- 新增表

apps/web-app/src/[模块]/trpc/[名称].ts

- 新增路由

apps/web-app/src/routes/app/[路径]/route.tsx

- 新增页面

Implementation Notes

实现说明

Patterns to Follow

需要遵循的模式

TRPC: See
```
trpc-patterns
```
skill
Frontend: See
```
tanstack-frontend
```
skill

TRPC：参考
```
trpc-patterns
```
Skill
前端：参考
```
tanstack-frontend
```
Skill

Testing

测试

Unit tests in
```
packages/services/src/__tests__/
```
E2E tests in
```
apps/web-app/e2e/
```

单元测试放在
```
packages/services/src/__tests__/
```
E2E测试放在
```
apps/web-app/e2e/
```

Assumptions

假设条件

[Any defaults used for unanswered questions]

undefined

[未回答问题使用的所有默认值]

undefined

Metadata Structure

元数据结构

json

{
  "id": "feature-slug",
  "started": "ISO-8601-timestamp",
  "lastUpdated": "ISO-8601-timestamp",
  "status": "active",
  "phase": "discovery|context|detail|complete",
  "progress": {
    "discovery": { "answered": 0, "total": 5 },
    "detail": { "answered": 0, "total": 5 }
  },
  "contextFiles": ["paths/of/files/analyzed"],
  "relatedFeatures": ["similar features found"]
}

json

{
  "id": "feature-slug",
  "started": "ISO-8601-timestamp",
  "lastUpdated": "ISO-8601-timestamp",
  "status": "active",
  "phase": "discovery|context|detail|complete",
  "progress": {
    "discovery": { "answered": 0, "total": 5 },
    "detail": { "answered": 0, "total": 5 }
  },
  "contextFiles": ["paths/of/files/analyzed"],
  "relatedFeatures": ["similar features found"]
}

Phase Transitions

阶段切换

After each phase, announce: "Phase complete. Starting [next phase]..."
Save all work before moving to next phase
User can check progress anytime with
```
/requirements-status
```

每个阶段完成后，提示："阶段完成。开始[下一阶段]..."
进入下一阶段前保存所有工作
用户可随时使用
```
/requirements-status
```
查看进度

End Workflow

结束工作流

Finalize the current requirement gathering session.

结束当前的需求收集会话。

Instructions

操作说明

Read
```
requirements/.current-requirement
```

If no active requirement:

No active requirement to end.

Use /requirements-list to see all requirements.

Show current status and ask user intent:

Ending requirement: [name]
Current phase: [phase] ([X/Y] complete)

What would you like to do?

1. Generate spec with current information
2. Mark as incomplete for later
3. Cancel and delete

Choose (1/2/3):

Based on choice:

读取
```
requirements/.current-requirement
```

如果没有正在进行的需求收集任务：

没有可结束的进行中需求收集任务。

使用 /requirements-list 查看所有需求。

显示当前状态并询问用户意图：

即将结束需求：[名称]
当前阶段：[阶段]（已完成[X/Y]）

请选择你要执行的操作：

1. 基于现有信息生成规格说明
2. 标记为未完成，稍后继续
3. 取消并删除

请选择（1/2/3）：

基于选择执行对应操作：

Option 1: Generate Spec

选项1：生成规格说明

Create
```
06-requirements-spec.md
```
Include all answered questions
Add defaults for unanswered with "ASSUMED:" prefix
Generate implementation hints based on project patterns
Update
```
metadata.json
```
status to "complete"

Spec format:

markdown

undefined

创建
```
06-requirements-spec.md
```
包含所有已回答的问题
未回答的问题使用默认值，添加"ASSUMED:"前缀
基于项目模式生成实现提示
将
```
metadata.json
```
的状态更新为"complete"

规格格式：

markdown

undefined

Requirements Specification: [Name]

需求规格说明：[名称]

Generated: [timestamp] Status: Complete with [N] assumptions

生成时间：[timestamp] 状态：已完成，包含[N]个假设条件

Overview

概述

[Problem statement from initial request] [Solution summary based on answers]

[初始请求中的问题陈述] [基于答案的解决方案摘要]

Functional Requirements

功能需求

[Based on answered questions]

[基于已回答问题生成]

User Stories

用户故事

As a [role], I want to [action] so that [benefit]

作为[角色]，我想要[操作]，以便[收益]

Acceptance Criteria

验收标准

[Criterion based on answers]

[基于答案生成的验收条件]

Technical Requirements

技术需求

Database Changes

数据库变更

[If applicable based on answers]

[如果基于回答需要变更则列出]

TRPC Router

TRPC路由

Location:
```
apps/web-app/src/[module]/trpc/
```
Procedures needed: [list]

位置：
```
apps/web-app/src/[模块]/trpc/
```
需要的接口：[列表]

Frontend Routes

前端路由

Path:
```
/app/[route]
```
Components: [list]

路径：
```
/app/[路由]
```
组件：[列表]

Files to Create/Modify

需要创建/修改的文件

[Specific paths in project codebase]

[项目代码库中的具体路径]

Implementation Notes

实现说明

Patterns to Follow

需要遵循的模式

TRPC: Load skill
```
trpc-patterns
```
Frontend: Load skill
```
tanstack-frontend
```

TRPC：加载
```
trpc-patterns
```
Skill
前端：加载
```
tanstack-frontend
```
Skill

Validation

校验

Run
```
bun run check
```
after implementation
Add E2E tests if user-facing

实现完成后运行
```
bun run check
```
如果是面向用户的功能添加E2E测试

Assumptions (REVIEW THESE)

假设条件（请务必查看）

[List any defaults used for unanswered questions]

ASSUMED: [Question] -> [Default used] because [reason]

[未回答问题使用的所有默认值列表]

假设：[问题] -> [使用的默认值]，原因是[理由]

Next Steps

下一步

Review assumptions above
Start implementation
Run
```
/code-review
```
before PR

undefined

查看上方的假设条件
开始实现
提交PR前运行
```
/code-review
```

undefined

Option 2: Mark Incomplete

选项2：标记为未完成

Update

metadata.json

json

{
  "status": "incomplete",
  "lastUpdated": "[timestamp]",
  "pausedAt": "[phase]",
  "remainingQuestions": [N]
}

Create summary of progress
Note what's still needed

Output:

Requirement marked as incomplete.

Progress saved:
- Phase: [current phase]
- Questions answered: [X/Y]
- Last activity: [now]

To resume later: /requirements-status

更新

metadata.json

：

json

{
  "status": "incomplete",
  "lastUpdated": "[timestamp]",
  "pausedAt": "[phase]",
  "remainingQuestions": [N]
}

创建进度摘要
标注还需要完成的内容

输出：

需求已标记为未完成。

进度已保存：
- 阶段：[当前阶段]
- 已回答问题：[X/Y]
- 最后操作时间：[当前时间]

稍后恢复：/requirements-status

Option 3: Cancel

选项3：取消

Confirm deletion:

Are you sure you want to delete this requirement?
All gathered information will be lost.

Type 'yes' to confirm:

If confirmed:
- Remove requirement folder
- Clear
```
.current-requirement
```

Output:

Requirement cancelled and deleted.

Start fresh: /requirements-start [description]

确认删除：

你确定要删除这个需求吗？
所有已收集的信息都会丢失。

输入'yes'确认：

如果确认：
- 删除需求文件夹
- 清空
```
.current-requirement
```

输出：

需求已取消并删除。

开启新需求收集：/requirements-start [description]

Post-Completion

完成后操作

After generating spec (Option 1):

Clear
```
.current-requirement
```

Show summary:

Requirements complete!

Spec saved: requirements/[folder]/06-requirements-spec.md

Next steps:
1. Review the spec, especially ASSUMPTIONS section
2. Start implementation
3. Use /code-review before creating PR

View spec: Read @requirements/[folder]/06-requirements-spec.md

生成规格说明后（选项1）：

清空
```
.current-requirement
```

显示摘要：

需求收集完成！

规格已保存：requirements/[folder]/06-requirements-spec.md

下一步：
1. 查看规格，尤其是假设条件部分
2. 开始实现
3. 创建PR前使用 /code-review

查看规格：读取 @requirements/[folder]/06-requirements-spec.md

Status Workflow

状态查看工作流

Show current requirement gathering progress and continue from last question.

显示当前需求收集进度，从上次未回答的问题继续。

Instructions

操作说明

Read
```
requirements/.current-requirement
```

If no active requirement:

No active requirement gathering session.

Options:
- Start new: /requirements-start [description]
- List all: /requirements-list

If active requirement exists:
- Read
```
metadata.json
```
  for current phase and progress
- Show formatted status
- Load appropriate question/answer files
- Continue from last unanswered question

读取
```
requirements/.current-requirement
```

如果没有正在进行的需求收集任务：

没有进行中的需求收集会话。

可选操作：
- 开启新会话：/requirements-start [description]
- 查看所有需求：/requirements-list

如果有正在进行的需求收集任务：
- 读取
```
metadata.json
```
  获取当前阶段和进度
- 显示格式化的状态
- 加载对应的问答文件
- 从上次未回答的问题继续

Status Display Format

状态显示格式

Active Requirement: [name]
Started: [time ago]
Phase: [Discovery/Context/Detail/Complete]
Progress: [X/Y] questions answered

--- Recent Progress ---

[Show last 3 answered questions with responses]

--- Next Question ---

[Show next unanswered question with default]

Type 'yes', 'no', or 'idk' (uses default)

进行中需求：[名称]
开启时间：[多久之前]
阶段：[探索/上下文收集/细节确认/已完成]
进度：已回答[X/Y]个问题

--- 最近进度 ---

[显示最近3个已回答的问题及答案]

--- 下一个问题 ---

[显示下一个未回答的问题及默认值]

输入'yes'、'no'或'idk'（使用默认值）

Continuation Flow

继续流程

Read next unanswered question from file:
- Phase 2:
```
01-discovery-questions.md
```
- Phase 4:
```
04-detail-questions.md
```
Present to user with default
Accept response:
- ```
yes
```
  /
```
y
```
  - Affirmative
- ```
no
```
  /
```
n
```
  - Negative
- ```
idk
```
  /
```
default
```
  /
```
d
```
  - Use default value
DO NOT record answer yet - wait until ALL questions in phase are asked
After ALL questions answered:
- Update answer file (
```
02-discovery-answers.md
```
  or
```
05-detail-answers.md
```
  )
- Update
```
metadata.json
```
  progress
Move to next question or phase

从文件中读取下一个未回答的问题：
- 阶段2：
```
01-discovery-questions.md
```
- 阶段4：
```
04-detail-questions.md
```
向用户展示问题及默认值
接收回复：
- ```
yes
```
  /
```
y
```
  - 是
- ```
no
```
  /
```
n
```
  - 否
- ```
idk
```
  /
```
default
```
  /
```
d
```
  - 使用默认值
暂不记录答案 - 等待当前阶段所有问题都提问完毕后再统一记录
所有问题回答完毕后：
- 更新答案文件（
```
02-discovery-answers.md
```
  或
```
05-detail-answers.md
```
  ）
- 更新
```
metadata.json
```
  中的进度
进入下一个问题或下一阶段

Phase Transitions

阶段切换

Discovery (Phase 2) -> Context (Phase 3):

All 5 discovery questions answered
Record answers in
```
02-discovery-answers.md
```
Run autonomous context gathering (no user interaction)
Create
```
03-context-findings.md
```

Context (Phase 3) -> Detail (Phase 4):

Context findings documented
Generate expert questions based on findings
Write to
```
04-detail-questions.md
```
Begin asking detail questions

Detail (Phase 4) -> Complete (Phase 5):

All detail questions answered
Record answers in
```
05-detail-answers.md
```
Generate final spec in
```
06-requirements-spec.md
```
Update status to "complete"
Clear
```
.current-requirement
```

探索阶段（阶段2）-> 上下文收集阶段（阶段3）：

5个探索问题全部回答完毕
将答案记录到
```
02-discovery-answers.md
```
执行自主上下文收集（无需用户交互）
创建
```
03-context-findings.md
```

上下文收集阶段（阶段3）-> 细节确认阶段（阶段4）：

上下文发现结果已记录
基于发现结果生成专业问题
写入
```
04-detail-questions.md
```
开始提问细节问题

细节确认阶段（阶段4）-> 完成（阶段5）：

所有细节问题回答完毕
将答案记录到
```
05-detail-answers.md
```
在
```
06-requirements-spec.md
```
中生成最终规格说明
更新状态为"complete"
清空
```
.current-requirement
```

Quick Actions

快捷操作

Continue: Just respond to the question
Skip phase: /requirements-end (generates spec with current info)
View all: /requirements-current
List all: /requirements-list

继续：直接回复问题即可
跳过阶段：/requirements-end（基于现有信息生成规格）
查看所有详情：/requirements-current
列出所有需求：/requirements-list

Current Workflow

当前需求详情工作流

Display detailed information about the active requirement. This is view-only — it does not continue gathering.

显示进行中需求的详细信息。此功能仅用于查看 — 不会继续收集流程。

Instructions

操作说明

Read
```
requirements/.current-requirement
```

If no active requirement:

No active requirement.

Recent completed requirements:
[Show last 3 completed with dates]

Start new: /requirements-start [description]
List all: /requirements-list

For active requirement:
- Load all files from requirement folder
- Display comprehensive status
- Show codebase analysis overview
- Show all questions and answers so far
- Display context findings if available
- Indicate current phase and next steps

读取
```
requirements/.current-requirement
```

如果没有进行中的需求：

没有进行中的需求。

最近完成的需求：
[显示最近3个已完成的需求及日期]

开启新需求：/requirements-start [description]
列出所有需求：/requirements-list

对于进行中的需求：
- 加载需求文件夹中的所有文件
- 显示完整的状态信息
- 显示代码库分析概览
- 显示至今所有的问题和答案
- 如果有上下文发现结果则展示
- 标注当前阶段和下一步操作

File Structure

文件结构

requirements/[timestamp]-[slug]/
├── 00-initial-request.md    # Original user request
├── 01-discovery-questions.md # Context discovery questions
├── 02-discovery-answers.md   # User's answers (after all asked)
├── 03-context-findings.md    # AI's codebase analysis
├── 04-detail-questions.md    # Expert requirements questions
├── 05-detail-answers.md      # User's detailed answers
├── 06-requirements-spec.md   # Final requirements document
└── metadata.json             # Status tracking

requirements/[timestamp]-[slug]/
├── 00-initial-request.md    # 用户原始需求
├── 01-discovery-questions.md # 上下文探索问题
├── 02-discovery-answers.md   # 用户的探索阶段答案（所有问题提问完毕后生成）
├── 03-context-findings.md    # AI生成的代码库分析结果
├── 04-detail-questions.md    # 专业需求问题
├── 05-detail-answers.md      # 用户的细节阶段答案
├── 06-requirements-spec.md   # 最终需求文档
└── metadata.json             # 状态跟踪

Display Format

显示格式

===========================================
Current Requirement: [name]
===========================================

Duration: [time since start]
Phase: [Initial Setup/Discovery/Context/Detail/Complete]
Progress: [total answered]/[total questions]

-------------------------------------------
INITIAL REQUEST
-------------------------------------------

[Content from 00-initial-request.md]

-------------------------------------------
CODEBASE OVERVIEW (Phase 1)
-------------------------------------------

Architecture: TanStack Start + TRPC + PostgreSQL + Drizzle
Relevant modules identified:
- [module 1]: [why relevant]
- [module 2]: [why relevant]

-------------------------------------------
DISCOVERY PHASE (5/5 complete)
-------------------------------------------

Q1: Will this be organization-scoped? YES
Q2: Will users interact through a new page? YES
Q3: Does this require new database tables? NO
Q4: Will this integrate with external APIs? NO (default)
Q5: Should this be accessible to all members? YES

-------------------------------------------
CONTEXT FINDINGS
-------------------------------------------

Similar Features Found:
- [Feature] at [path] - [pattern to follow]

Files to Modify:
- apps/web-app/src/[module]/trpc/[router].ts
- packages/db/src/schema.ts (if needed)

Patterns Identified:
- TRPC: [pattern reference]
- Frontend: [pattern reference]

-------------------------------------------
EXPERT QUESTIONS (2/5 answered)
-------------------------------------------

Q1: Extend existing UserRouter? YES
Q2: Follow pattern from ProjectSettings? YES
Q3: Cache data in TanStack Query? [PENDING]
Q4: Add E2E tests? [PENDING]
Q5: Validation on both client and server? [PENDING]

-------------------------------------------
NEXT ACTION
-------------------------------------------

Current: Answering expert question Q3

Options:
- Continue: /requirements-status
- End early: /requirements-end
- View all: /requirements-list

===========================================
当前需求：[名称]
===========================================

持续时间：[从开始到现在的时长]
阶段：[初始设置/探索/上下文收集/细节确认/已完成]
进度：已回答[总已回答数]/[总问题数]个问题

-------------------------------------------
初始需求
-------------------------------------------

[00-initial-request.md 中的内容]

-------------------------------------------
代码库概览（阶段1）
-------------------------------------------

架构：TanStack Start + TRPC + PostgreSQL + Drizzle
识别到的相关模块：
- [模块1]：[相关原因]
- [模块2]：[相关原因]

-------------------------------------------
探索阶段（已完成5/5）
-------------------------------------------

Q1: 该功能是否为组织级？是
Q2: 用户是否需要通过新页面访问？是
Q3: 是否需要新建数据库表？否
Q4: 是否需要对接外部API？否（默认值）
Q5: 是否对所有组织成员开放？是

-------------------------------------------
上下文发现结果
-------------------------------------------

找到的相似功能：
- [功能] 位于 [路径] - [需要遵循的模式]

需要修改的文件：
- apps/web-app/src/[模块]/trpc/[路由].ts
- packages/db/src/schema.ts（如果需要）

识别到的模式：
- TRPC：[模式参考]
- 前端：[模式参考]

-------------------------------------------
专业问题（已回答2/5）
-------------------------------------------

Q1: 是否扩展现有UserRouter？是
Q2: 是否遵循ProjectSettings的模式？是
Q3: 是否将数据缓存到TanStack Query？[待回答]
Q4: 是否添加E2E测试？[待回答]
Q5: 是否在客户端和服务端都做校验？[待回答]

-------------------------------------------
下一步操作
-------------------------------------------

当前：回答专业问题Q3

可选操作：
- 继续：/requirements-status
- 提前结束：/requirements-end
- 查看所有需求：/requirements-list

Important Notes

重要说明

This is view-only (doesn't continue gathering)
Shows complete history and context
Use
```
/requirements-status
```
to continue answering questions
All file paths are relative to project root

此功能仅用于查看（不会继续收集流程）
展示完整的历史和上下文
使用
```
/requirements-status
```
继续回答问题
所有文件路径都是相对于项目根目录的

List Workflow

需求列表工作流

Display all requirements with their status and summaries.

显示所有需求及其状态和摘要。

Instructions

操作说明

Check
```
requirements/.current-requirement
```
for active requirement
List all folders in
```
requirements/
```
directory
For each requirement folder:
- Read
```
metadata.json
```
- Extract key information
- Format for display
Sort by:
- Active first (if any)
- Then by status: complete, incomplete
- Then by date (newest first)

检查
```
requirements/.current-requirement
```
获取进行中的需求
列出
```
requirements/
```
目录下的所有文件夹
对每个需求文件夹：
- 读取
```
metadata.json
```
- 提取关键信息
- 格式化显示
排序规则：
- 进行中的需求优先
- 然后按状态：已完成、未完成
- 然后按日期（最新的在前）

Display Format

显示格式

Requirements Documentation

--- ACTIVE ---

[name]
   Phase: Discovery (3/5) | Started: 30m ago
   Request: [first line of 00-initial-request.md]
   Next: Continue with /requirements-status

--- COMPLETE ---

2025-01-26-0900-dark-mode-toggle
   Status: Ready for implementation
   Questions answered: 10
   Summary: [first line of spec overview]
   Spec: requirements/2025-01-26-0900-dark-mode-toggle/06-requirements-spec.md

2025-01-25-1400-export-reports
   Status: Implemented
   Questions answered: 10
   Summary: PDF/CSV export with filtering

--- INCOMPLETE ---

2025-01-24-1100-notification-system
   Status: Paused at Detail phase (2/5)
   Last activity: 2 days ago
   Resume: /requirements-status

--- STATISTICS ---

Total: 4 requirements
- Complete: 2
- Active: 1
- Incomplete: 1

需求文档

--- 进行中 ---

[名称]
   阶段：探索（3/5） | 开启时间：30分钟前
   需求：[00-initial-request.md 的第一行]
   下一步：使用 /requirements-status 继续

--- 已完成 ---

2025-01-26-0900-dark-mode-toggle
   状态：可开始实现
   已回答问题：10个
   摘要：[规格说明概述的第一行]
   规格：requirements/2025-01-26-0900-dark-mode-toggle/06-requirements-spec.md

2025-01-25-1400-export-reports
   状态：已实现
   已回答问题：10个
   摘要：支持筛选的PDF/CSV导出功能

--- 未完成 ---

2025-01-24-1100-notification-system
   状态：暂停在细节阶段（2/5）
   最后操作时间：2天前
   恢复：/requirements-status

--- 统计 ---

总计：4个需求
- 已完成：2个
- 进行中：1个
- 未完成：1个

Stale Detection

过期检测

Mark if incomplete > 7 days:

2025-01-15-old-feature (STALE - 8 days)
   Consider: Resume or cancel with /requirements-end

如果未完成需求超过7天则标记：

2025-01-15-old-feature（已过期 - 8天）
   建议：使用 /requirements-end 恢复或取消

Linked Artifacts

关联产物

For complete requirements, check if there are:

Related git branches
Pull requests (search git log for requirement name)
Implementation status

对于已完成的需求，检查是否存在：

关联的git分支
Pull Request（在git日志中搜索需求名称）
实现状态

Quick Actions

快捷操作

Quick Actions:
- View active detail: /requirements-current
- Resume incomplete: /requirements-status
- Start new: /requirements-start [description]
- End/cancel active: /requirements-end

快捷操作：
- 查看进行中需求详情：/requirements-current
- 恢复未完成需求：/requirements-status
- 开启新需求：/requirements-start [description]
- 结束/取消进行中需求：/requirements-end

Empty State

空状态

If no requirements exist:

No requirements found.

Start gathering requirements for a new feature:
/requirements-start [feature description]

Example:
/requirements-start add dark mode toggle to settings

如果没有需求：

未找到任何需求。

开始收集新功能的需求：
/requirements-start [功能描述]

示例：
/requirements-start add dark mode toggle to settings

Remind Workflow

提醒工作流

Quick correction when deviating from requirements gathering rules.

当偏离需求收集规则时快速校正。

Instructions

操作说明

Check
```
requirements/.current-requirement
```
If no active requirement:
- Show "No active requirement gathering session"
- Exit
Display reminder based on current context:

🔔 Requirements Gathering Reminder

You are gathering requirements for: [active-requirement]
Current phase: [Initial Setup/Context Discovery/Targeted Context/Expert Requirements]
Progress: [X/Y questions]

📋 PHASE-SPECIFIC RULES:

Phase 2 - Context Discovery:
- ✅ Ask 5 yes/no questions about the problem space
- ✅ Questions for product managers (no code knowledge required)
- ✅ Focus on user workflows, not technical details
- ✅ Write ALL questions before asking any
- ✅ Record answers ONLY after all questions asked

Phase 3 - Targeted Context (Autonomous):
- ✅ Use RepoPrompt tools to search and read code
- ✅ Analyze similar features and patterns
- ✅ Document findings in context file
- ❌ No user interaction during this phase

Phase 4 - Expert Requirements:
- ✅ Ask 5 detailed yes/no questions
- ✅ Questions as if speaking to PM who knows no code
- ✅ Clarify expected system behavior
- ✅ Reference specific files when relevant
- ✅ Record answers ONLY after all questions asked

🚫 GENERAL RULES:
1. ❌ Don't start coding or implementing
2. ❌ Don't ask open-ended questions
3. ❌ Don't record answers until ALL questions in phase are asked
4. ❌ Don't exceed 5 questions per phase

📍 CURRENT STATE:
- Last question: [Show last question]
- User response: [pending/answered]
- Next action: [Continue with question X of 5]

Please continue with the current question or read the next one from the file.

检查
```
requirements/.current-requirement
```
如果没有进行中的需求收集会话：
- 显示"没有进行中的需求收集会话"
- 退出
基于当前上下文显示提醒：

🔔 需求收集提醒

你正在为以下需求收集信息：[进行中需求名称]
当前阶段：[初始设置/上下文探索/定向上下文收集/专业需求确认]
进度：已回答[X/Y]个问题

📋 阶段专属规则：

阶段2 - 上下文探索：
- ✅ 提出5个关于问题范围的是非问题
- ✅ 面向产品经理提问（无需代码知识）
- ✅ 聚焦用户工作流，而非技术细节
- ✅ 提问前先将所有问题写入文件
- ✅ 所有问题提问完毕后再统一记录答案

阶段3 - 定向上下文收集（自主执行）：
- ✅ 使用RepoPrompt工具搜索和读取代码
- ✅ 分析相似功能和实现模式
- ✅ 将发现结果写入上下文文件
- ❌ 此阶段无需用户交互

阶段4 - 专业需求确认：
- ✅ 提出5个详细的是非问题
- ✅ 像和不懂代码的产品经理沟通一样提问
- ✅ 明确预期的系统行为
- ✅ 相关时引用具体文件路径
- ✅ 所有问题提问完毕后再统一记录答案

🚫 通用规则：
1. ❌ 不要开始编码或实现
2. ❌ 不要提出开放式问题
3. ❌ 阶段内所有问题未提问完毕前不要记录答案
4. ❌ 每个阶段提问不超过5个

📍 当前状态：
- 上一个问题：[显示上一个问题]
- 用户回复：[待回复/已回答]
- 下一步操作：[继续回答第X个问题，共5个]

请继续回答当前问题，或从文件中读取下一个问题。

Common Correction Scenarios

常见校正场景

Open-ended question asked:

"Let me rephrase as a yes/no question..."

Multiple questions asked:

"Let me ask one question at a time..."

Implementation started:

"I apologize. Let me continue with requirements gathering..."

No default provided:

"Let me add a default for that question..."

提出了开放式问题：

"我将重新表述为是非问题..."

一次提出了多个问题：

"我将每次只提一个问题..."

开始实现了：

"抱歉，我将继续进行需求收集..."

未提供默认值：

"我将为该问题添加默认值..."

Auto-trigger Patterns

自动触发规则

Detect code blocks → remind no implementation
Multiple "?" in response → remind one question
Response > 100 words → remind to be concise
Open-ended words ("what", "how") → remind yes/no only

检测到代码块 → 提醒不要开始实现
回复中包含多个"？" → 提醒一次只提一个问题
回复超过100字 → 提醒保持简洁
出现开放式疑问词（"什么"、"如何"） → 提醒仅使用是非问题

Important Rules

重要规则

These rules apply across all phases of requirements gathering:

ONLY yes/no questions with smart defaults — never open-ended questions
ONE question at a time — never ask multiple questions in a single message
Write ALL questions to file BEFORE asking any — prepare the full set first, then ask sequentially
Stay focused on requirements — no implementation, no code, no technical solutions during gathering
Use actual file paths from codebase — reference real paths like
```
apps/web-app/src/[module]/trpc/
```
not generic placeholders
Document WHY each default makes sense — every default must have a rationale (e.g., "most project features are org-scoped")
Reference similar existing features as examples — ground questions in concrete codebase patterns
Do NOT record answers until ALL questions in a phase are asked — collect all responses before writing to answer files
Phase 3 is fully autonomous — no user interaction during targeted context gathering
Maximum 5 questions per phase — keep each phase focused and bounded

这些规则适用于需求收集的所有阶段：

仅使用是非问题并搭配智能默认值 — 绝对不要提出开放式问题
每次仅提一个问题 — 绝对不要在单条消息中提出多个问题
提问前先将所有问题写入文件 — 先准备好完整的问题列表，再按顺序提问
聚焦于需求收集 — 收集过程中不要讨论实现、代码、技术方案
使用代码库中的实际文件路径 — 引用真实路径如
```
apps/web-app/src/[模块]/trpc/
```
，不要使用通用占位符
说明每个默认值的合理性 — 每个默认值都要有理由（例如："多数项目功能都是组织级"）
引用相似的现有功能作为示例 — 基于具体的代码库模式提出问题
阶段内所有问题未提问完毕前不要记录答案 — 收集完所有回复后再统一写入答案文件
阶段3完全自主执行 — 定向上下文收集阶段无需用户交互
每个阶段最多5个问题 — 保持每个阶段聚焦可控