devdocs-requirements

Requirement Expansion

Expand the user's brief requirements into a structured requirements document, establishing an associated system of feature points, user stories, and acceptance criteria.

Language Rules

• Support questions in Chinese and English
• Reply uniformly in Chinese
• Generate documents in Chinese

Trigger Conditions

• The user provides functional requirements or ideas
• The user requests to create/write a PRD
• The user wants to clarify or record requirements
• From /devdocs-feature incremental requirement delegation
• The user needs to supplement project background information (especially after retrofit)
• The user provides reference materials, domain knowledge, technical constraints

Operating Modes

/devdocs-requirements              → 自动检测模式
/devdocs-requirements --incremental → 强制增量模式（追加功能点）
/devdocs-requirements --context     → 背景信息模式（追加/更新背景）
/devdocs-requirements --fast        → 跳过 Plan 模式，直接生成，仅最终确认

Mode	Trigger Condition	Description
Initial Mode	None 01-requirements.md	Create a requirements document from scratch
Incremental Mode	Existing 01-requirements.md	Scan numbering + append feature points/user stories/acceptance criteria
Background Information Mode	--context Or the user wants to supplement background	Append/update the "Background and Goals" section

--fast Mode

--fast Can be combined with any mode, behavior changes:

• Skip the EnterPlanMode step (Initial Mode)
• Use reasonable defaults (do not ask about tech stack preferences, etc.)
• Keep only 1 confirmation before the final write
• Default behavior unchanged,--fast is opt-in

Workflow

Initial Mode

1. 收集原始需求
   │
   ├── 记录用户原话或关键表述
   ├── 标记来源（口述/邮件/Issue/会议纪要）
   └── 记录日期
   │
   ▼
2. 理解需求 + 探索代码库（如适用）
   │
   ▼
3. 进入 Plan 模式 → 呈现需求拆解方案
   │              （功能点划分、边界范围、优先级）
   ▼
4. 用户审批 Plan → 确认拆解方向或调整
   │
   ▼
5. 退出 Plan 模式 → 生成需求文档：识别功能点 (F-XXX)
   │
   ▼
6. 文档编写：用户故事 (US-XXX)
   │
   ▼
7. 文档编写：验收标准 (AC-XXX)
   │
   ▼
8. 生成追溯矩阵
   │
   ▼
9. 用户确认

Incremental Mode

1. 扫描现有编号
   │
   ├── 读取 01-requirements.md
   └── 获取 F/US/AC 最大编号
   │
   ▼
2. 收集新增原始需求
   │
   ├── 记录用户原话，追加到 `## 0. 原始需求` 表格
   └── 若该章节不存在（历史文档），标注"缺失历史原始需求"后继续
   │
   ▼
3. 理解新增需求
   │
   ▼
4. 追加功能点/用户故事/验收标准
   │
   ├── 延续现有编号
   └── 标注增量版本和日期
   │
   ▼
5. 更新追溯矩阵
   │
   ▼
6. 用户确认
   │
   ▼
7. 返回新增编号列表（供调用方使用）

Background Information Mode

1. 读取现有文档
   │
   ├── 检查 01-requirements.md 是否存在
   └── 提取现有"背景与目标"章节内容
   │
   ▼
2. 收集背景信息
   │
   ├── 引导用户提供信息（AskUserQuestion）
   ├── 接收用户直接输入
   ├── 从文件路径提取（Read）
   └── 从 URL 提取摘要（WebFetch）
   │
   ▼
3. 整合信息
   │
   ├── 合并到"背景与目标"章节
   ├── 补充到"技术约束"子章节
   └── 补充到"参考资料"子章节
   │
   ▼
4. 更新文档
   │
   ▼
5. 用户确认

Context Management

Batching Principle

Expand in batches by feature point (F-XXX), with each batch completing all user stories and acceptance criteria for one feature point.

Quality Anchor

• The US/AC of the first feature point serve as thequality anchor
• Before starting each new feature point, review the level of detail of the first batch (specificity of the US role/expectation/purpose, quantifiability of the AC, completeness of the GWT format)
• If the current batch's level of detail is noticeably lower than the anchor, supplement it immediately

Consistency Self-Check

After completing the expansion of each feature point, compare and check:

• Whether the US format is consistent with the first batch (complete with the three elements of role/expectation/purpose)
• Whether the AC is quantifiable and verifiable (not vague descriptions like "the system should work normally")
• Whether each US has 2-3 ACs (consistent coverage density)

Plan Mode Specification

Initial Mode onlyUse Plan Mode. Incremental Mode and Background Information Mode have clear directions and do not need Plan.

Initial Mode Plan Content

After understanding the requirements and exploring the code,you must use EnterPlanMode to present the requirement decomposition plan：

## 需求拆解方案

### 功能点划分
| 编号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| F-001 | ... | ... | P0 |
| F-002 | ... | ... | P1 |

### 范围边界
- 包含：<本次范围内的功能>
- 排除：<明确不做的功能>

### 关键决策
- <需要用户确认的拆解决策>

### 预估规模
- 功能点数量：X 个
- 用户故事数量：约 Y 个
- 验收标准数量：约 Z 个

Plan Mode Timing

Mode	Whether to Use Plan	Reason
Initial Mode	Yes	Once the F numbering is established, all downstream references depend on it, and the cost of change is high
Incremental Mode	No	The append direction is clear, and the numbering continues the existing system
Background Information Mode	No	Information integration, no architectural decisions

Numbering specification

Type	Prefix	Format	Example
Feature	F	F-XXX	F-001, F-002
User Story	US	US-XXX	US-001, US-002
Acceptance Criteria	AC	AC-XXX	AC-001, AC-002

Numbering rules：

• Global sequential numbering, not nested
• Express relationships through a traceability matrix
• Once a number is assigned, it cannot be reused

Output files

Main file：docs/devdocs/01-requirements.md

If the document exceeds 300 lines, it can be split into:

• 01-requirements.md - Overview and feature points
• 01-requirements-stories.md - User story details
• 01-requirements-nfr.md - Non-functional requirements

For detailed templates, see templates/requirements-template.md

Document structure

# 需求文档：<功能名称>

## 0. 原始需求
## 1. 背景与目标
## 2. 功能点清单
## 3. 用户故事
## 4. 验收标准
## 5. 追溯矩阵
## 6. 非功能性需求
## 7. 范围边界
## 8. 风险与假设

## 0. 原始需求 Record the user's original words or key expressions as a baseline reference for requirement refinement. See the template for details.

Core concepts

• Feature (F-XXX): An independent functional unit perceivable by users, which can be delivered and verified independently
• User Story (US-XXX): Format: "As a <role>, I want <feature>, so that <value>"
• Acceptance Criteria (AC-XXX): Quantifiable, verifiable completion conditions, at least 2-3 per US
• Traceability matrix: Shows the relationships F → US → AC

For detailed formats and examples, see templates/requirements-template.md

Incremental mode details

Number scan

Extract the maximum number from existing documents:

## 当前状态

| 类型 | 当前最大编号 | 下一编号 |
|------|-------------|----------|
| 功能点 (F) | F-003 | F-004 |
| 用户故事 (US) | US-008 | US-009 |
| 验收标准 (AC) | AC-015 | AC-016 |

Append format

---

## 功能迭代 v2: <功能名称> (2024-01-15)

> 本次新增 F-004，包含 2 个用户故事、5 个验收标准。

### F-004: <功能名称>

**描述**：<功能描述>

**用户故事**：

| 编号 | 角色 | 期望 | 目的 |
|------|------|------|------|
| US-009 | 作为<角色> | 我希望<功能> | 以便于<价值> |

**验收标准**：

- [ ] AC-016: <标准1>
- [ ] AC-017: <标准2>

Return value

After incremental mode is complete, return the list of newly added numbers for the caller to use:

新增编号：
- F-004
- US-009, US-010
- AC-016 ~ AC-020

Background information mode details

When entering --context mode, you must read context-mode.md to obtain the information collection guidance, input methods, and document structure template.

Constraints

Phase boundary constraints (highest priority)

• This Skill only produces documents; writing or generating any implementation code (source code, scripts, configuration changes) is strictly prohibited
• The Write tool is only used to write docs/devdocs/ Markdown documents under
• After exiting Plan mode, execute document writing (not code implementation)
• Coding implementation is handled by /devdocs-dev-workflow and is not covered by this Skill

Feature constraints

• Each feature must have a unique number (F-XXX)
• Features must be marked with priority (P0/P1/P2)
• Feature descriptions should be concise and clear

User story constraints

• Each user story must be associated with a feature
• Must follow the "As a... I want... so that..." format
• Each feature must have at least 1 user story

User story quality check (INVEST)

Automatically verified during generation, no additional user interaction required:

• Independent: Can be delivered independently
• Negotiable: Details are negotiable
• Valuable: Valuable to users
• Estimable: Workload can be estimated
• Small: Can be completed in one iteration
• Testable: Can be verified through testing

Acceptance criteria constraints

• Each acceptance criterion must have a unique number (AC-XXX)
• Each user story must have at least 2 acceptance criteria
• Acceptance criteria must be quantifiable and verifiable
• Verification method must be described

Format options：

• Table format (default): suitable for simple conditions
• Given-When-Then: suitable for complex behavior scenarios
  • Given <precondition>
  • When <action>
  • Then <expected result>

Traceability constraints

• A traceability matrix must be provided
• All feature points must have corresponding user stories
• All user stories must have corresponding acceptance criteria

Incremental mode constraints

• Existing numbering must be scanned first, and numbering continued
• Appended content must be marked with the incremental version and date
• Existing content must not be deleted or overwritten
• A list of newly added numbers must be returned upon completion

Raw requirements constraints

• Initial mode: raw requirements must be collected before F/US/AC refinement and written to ## 0. 原始需求
• Incremental mode: new requirements must be appended to the ## 0. 原始需求 table
• Background information mode (--context): do not write to ## 0. 原始需求—unless what the user provides is the original wording of a requirement rather than a background supplement
• Raw requirements should retain the original wording or the minimum necessary rewriting
• If a historical document lacks this section, mark "missing historical raw requirements" and continue

Background information mode constraints

• The existing "Background and Goals" section content must be read first
• Existing background information must not be deleted or overwritten
• New content must be marked with the update date
• URL references must use WebFetch to extract a summary; merely recording the link is not allowed
• File references must use Read to verify that the file exists
• Sensitive information (keys, passwords, internal URLs) must not be written into the document
• Reference materials must indicate their purpose and relevance

Plan mode constraints

• Initial mode: after understanding the requirements + exploring the code, Plan mode must be entered
• The Plan must include feature point breakdown and scope boundaries
• Numbering allocation and document writing can begin only after the user approves the Plan
• When the user requests adjustments, update the Plan and re-approve it
• Incremental mode and background information mode do not use Plan mode

Confirmation constraints

• The completeness of feature points must be confirmed with the user
• Features not mentioned and not confirmed by the user must not be added

Context management constraints

• The level of detail of US/AC in later batches must be no lower than that of the first batch (format completeness, degree of quantification, coverage density)
• A consistency self-check must be performed after each feature point is completed

Skill collaboration

Scenario	Collaborating Skill	Description
New feature requirement	/devdocs-feature	Called: a new feature triggers requirement appending
Insight conversion	/devdocs-insights	Called: improvement suggestions are converted into requirements
Bug-exposed requirement	/devdocs-bugfix	Called: bug fixing reveals missing requirements
Project retrofit	/devdocs-retrofit	Called: reverse derivation generates requirements
Supplement background after retrofit	/devdocs-retrofit	Follow-up: after reverse engineering is completed, use --context to supplement the background
Design phase	/devdocs-system-design	Follow-up: After requirements confirmation, proceed to design
Context generation	/devdocs-onboard	Follow-up: Background information will be extracted into a context summary

Sub-Agent Summary Format

When this Skill runs as a sub-agent, return the following structured summary:

skill: devdocs-requirements
mode: initial | incremental
new_ids:
  features: [F-001~F-003]
  stories: [US-001~US-008]
  acceptance: [AC-001~AC-015]
status: completed
output_files:
  - docs/devdocs/01-requirements.md

Next Step

Completion mode	Suggested next step
Initial mode	/devdocs-system-design Proceed to system design
Incremental mode	/devdocs-system-design Incremental design or /devdocs-test-cases Supplementary testing
Background information mode	Continue /devdocs-requirements Define feature points, or /devdocs-system-design Design

Tip: When document changes are significant, it is recommended to run /agent-memory Sync memory files.