prd

Product Requirements Orchestrator

Orchestrates the product requirements processing workflow, automatically routing to brainstorm or PRD parsing, and produces structured requirement packages for keel to consume.

Quick Start

One-liner: Process vague ideas or large PRD documents, producing structured FR-XX/NFR-XX requirements.

Most common usage: /prd(automatically detects create/revise/continue)

Not suitable? Requirements already clear→/requirements

Detailed Documentation

• PRD revision boundary:references/governance/prd-revision-policy.md
• PRD ↔ keel Mapping：references/governance/prd-devdocs-mapping.md
• Shared constraints SSOT:../shared/constraints.md

This skill follows the shared constraints SSOT: gating markers, yaml-summary-v1, Task delegation, user confirmation, Recovery format, read-only / dry-run, FUTURE tri-state, realign / spec_version, see skills/shared/constraints.md. This file only describes PRD-private rules.

Language Rules

• Supports questions in Chinese and English
• Replies uniformly in Chinese

Positioning

用户 → /prd → 自动检测输入类型 → 路由到对应流程
                         ↓
              prd-brainstorm（想法澄清）
              prd-parser（文档拆分）
                         ↓
              结构化需求包 → keel 衔接

Core Value: Makes up for keel's insufficient handling of vague ideas and large PRDs, providing a complete path from requirement exploration to structured output.

Single-requirement scaffolding principle

docs/prd/ isa one-time scaffold for the current requirement, with a flat structure, serving only one in-flight requirement at any moment:

• No global index, numbering registry, archive, or iteration chain across requirements is maintained — multiple parallel requirements have been disproven in practice and removed.
• Requirement lifecycle:brainstorm/解析 → requirements → 设计 → 开发 → close(上线). Being /requirements --from-prd absorbed only meansentering the development flow, not the endpoint; during development the requirement can still be revised via --revise .
• After close (going live)the requirement ends,docs/prd/ can be /prd clear(or /pipeline close final step) cleaned up. The only source of truth is code + the why memory already absorbed into docs/devdocs/ ; history relies on git, not on docs/prd/ retention.

Operating Modes

/prd                 → 自动检测输入类型（默认感知已有系统）
/prd brainstorm      → 强制头脑风暴模式
/prd prd             → 强制 PRD 解析模式
/prd --revise FR-03  → 单个 FR 重新 brainstorm
/prd clear [--dry-run|--apply]  → 清理当前需求脚手架（close 收尾用）

New requirement gate (hard constraint)

/prd Before enteringthe new path(brainstorm / prd-parse), first detect the current scaffold to ensure "only the current requirement is stored":

1. Detect docs/prd/requirements/index.md whether it already exists.
2. Does not exist → greenfield, create directly, FR/NFR start from FR-01 / NFR-01 .
3. Already exists → ⚠️ Must confirm, AskUserQuestion with three choices:
   • Continue current requirement: append / revise on the existing scaffold (FR continues numbering, does not restart numbering);
   • Create new after close cleanup: jump to the /prd clear flow, clear it, then create anew from scratch;
   • Explicit discard / reset: after the user explicitly discards the current scaffold (clear docs/prd/), create anew from scratch.
4. Before confirmation, ⛔ directly overwriting and creating new is forbidden — preventing old requirements from being silently swallowed and old/new numbering from crossing (old mapping rows being mistakenly treated as mappings for new FRs).

Automatic Detection Logic

When there are no parameters or no mode is specified, analyze user input to route automatically:

分析用户输入
    |
    +-- 输入 < 200 字 + 无结构化标记 → brainstorm 完整模式
    |
    +-- 输入 > 2000 字 或引用大文件 → prd-parser + 逐块 brainstorm
    |
    +-- 用户明确指定模式 → 直接路由
    |
    +-- 模糊（200~2000 字，无法确定）→ AskUserQuestion 确认

Judgment criteria：

• "Unstructured markup" means no heading hierarchy, no numbered lists, no YAML front matter, etc.
• "Referencing a large file" means the user provides a file path and the file is > 2000 characters, or is in a binary format such as PDF/image
• For ambiguous ranges, ask: "The input falls between an idea and a document. Please confirm: (1) brainstorm as an idea (2) structurally parse as a document"

PRD private gating

Gating marker: see skills/shared/constraints.md § 1

Trigger point	Gating	Resume / Continue
When creating a new requirement, docs/prd/requirements/index.md already exists	⚠️ Must confirm	Choose one of three: continue the current requirement / clean up and create new with /prd clear / create new after explicit discard
Input is 200~2000 characters and it cannot be determined whether it is an idea or a document	⚠️ Must confirm	The user chooses "brainstorm as an idea" or "structurally parse as a document"
--revise target FR file does not exist	⛔ Prohibited from continuing	Error and exit; check the number or create that FR first
clear orphaned / unsynchronized requirement detected	⚠️ Must confirm	Delete only after explicit confirmation (see Clean up scaffolding）

Step 0: Context awareness (automatic, prerequisite for all scenarios)

On startup, automatically detect whether an existing system is present, without requiring the user to specify:

Item	Rule	Output
Code detection	Check whether git ls-files has non-document files, or detect common code file patterns	Code present → delegate to codebase-insight (its caching mechanism decides whether to rescan), read the returned docs/codebase-insight.md; no code → greenfield mode, skip
keel detection	Detect docs/devdocs/01-requirements.md	Exists → extract the existing F/US list as supplementary context; does not exist → skip
Design asset detection	According to references/design-context.md execute the detection protocol	Enter the normal orchestration flow at Step 1+ (brainstorm / prd-parse)

After carrying existing context, during brainstorm exploration annotate the relationship of each FR-XX to the existing system:

• Add to the FR-XX YAML relation field:new(brand-new feature) | extend(extend existing) | modify(modify existing)
• extend / modify When adding related_module field to annotate the associated existing module

--revise mode

Allows the user to re-enter brainstorm clarification for a single FR, without resubmitting the entire requirement:

/prd --revise FR-03
    |
    v
1. 定位 FR-03 文件：glob docs/prd/requirements/FR-03-*.md
   ⛔ 若文件不存在 → 报错退出（检查编号或先创建）
   记录实际路径（source_fr_path），后续回写使用同一路径
    |
    v
2. 提取 FR-03 的功能描述和验收意图，作为 brainstorm 上下文
    |
    v
3. Task: prd-brainstorm（完整模式）
    |  传入上下文：FR-03 现有功能描述 + 验收意图 + 用户修正说明
    |  约束：brainstorm 产出必须保持 FR-03 的 id 和编号不变
    |  输出：更新后的 FR-03 内容（不分配新编号）
    |
    v
4. 用 brainstorm 产出**原地覆盖** source_fr_path（保持 id: FR-03）+ 更新 requirements/index.md
    |
    v
5. 如果 FR-03 已有 keel 映射 → 将 mapping_status 置为 outdated
    |  提示：「FR-03 已映射为 F-XXX，建议重新运行 /requirements --from-prd 更新」

mapping_status specification

For detailed specification see references/prd-mapping-status.md(column definitions, status enums, authoritative row rules)

Clean up scaffolding (close wrap-up)

/prd clear After the requirement is closed (launched), clean up docs/prd/ one-time scaffolding. Usually delegated by the /pipeline close final step (executed after sync/compound/onboard have extracted the why memory completely), and can also be called independently.

dry-run → confirm → implement(by default, only --dry-run，--apply physically deletes):

1. Cleanup scope: list docs/prd/ The file/directory tree to be deleted below.
2. Impact analysis("safely absorbed" determination; only when all three conditions are satisfied can it be cleaned up):
   • Enumerate actual files: scan requirements/FR-*.md / NFR-*.md actually existing product_id, do not only trust the mapping table;
   • take the authoritative row: for each product_id, take the requirements/index.md in the ## keel 映射 tablelast rowas the authoritative status (you cannot ignore subsequent outdated/removed just because a historical row is active, see prd-mapping-status.md）；
   • verify keel actual existence: the authoritative row devdocs_id must actually exist in the docs/devdocs/01-requirements.md current F list;
   • only when "latest status ∈ {active, remapped} and target F exists in keel" → marksafe to clean up; all others (no mapping / outdated / removed / missing target) → ⚠️ orphan / unsynchronized highlight, by default do not delete.
3. ⚠️ Must confirm → --apply delete docs/prd/; when orphan / unsynchronized items exist, the confirmation text explicitly lists them.
4. When there is no docs/prd/ , silently skip (already cleaned up).

Orchestration flow

Scenario	Input	Steps	Output / gate
Brainstorming (idea → requirements)	User input (one sentence / brief idea)	Task: prd-brainstorm (full mode), converge via 5W1H → user journey → MoSCoW	Generate requirements/ small documents + index.md; maturity assessment → keel connection suggestions
PRD parsing (large document → chunks → requirements)	User provides PRD document	1. Task: prd-parser (convert + split → chunks/FR-XX.md + NFR-XX.md) 2. Block-by-block Task: prd-brainstorm --chunk <chunk文件路径>; adaptive depth: mature blocks are quickly confirmed, vague blocks are explored in depth; final classification: review the parser's FR/NFR initial judgment; example input:/prd-brainstorm --chunk docs/prd/chunks/FR-09-用户认证.md3. Cross-block synthesis: global terminology, shared assumptions, cross-cutting NFRs, conflict/duplicate resolution 4. Generate/update requirements/index.md overview 5. Maturity assessment	keel connection suggestions
PRD update (incremental processing)	User provides updated PRD	1. Task: prd-parser (re-split), calculate new document_fingerprint 2. Fingerprint comparison: match old and new blocks by chunk_key, compare source_fingerprint 3. Call prd-brainstorm only for outdated/pending blocks 4. Update index.md + re-evaluate maturity	Unchanged → keep clarified, skip; changed → mark outdated, brainstorm again; newly added → create new file, status=pending; deleted → mark removed, mark the corresponding requirement as invalid

Cross-block synthesis (Step 3 details)

In PRD scenarios, after all blocks are clarified, perform cross-block synthesis (synthesis of multiple chunks within a single requirement, written to requirements/index.md）：

Global terminology

Scan all requirements files, extract recurring domain terms, and write unified definitions to index.md.

Shared assumptions and constraints

Identify assumptions and constraints that do not belong to a single block but affect multiple requirements.

Cross-cutting NFRs

Identify non-functional requirements spanning multiple FRs (such as global performance metrics, security policies, compatibility requirements) and consolidate them into the Cross-cutting NFRs section of index.md.

Conflict and duplication resolution

• Content conflicts: different blocks describe the same feature inconsistently → record the conflict item, note the source block, suggest a resolution
• Duplication detection: multiple blocks describe the same feature → merge or annotate a primary-secondary relationship
• Classification conflicts: the brainstorm final judgment is inconsistent with the parser initial judgment → the brainstorm final judgment prevails, annotate in index.md 来源: FR-01 (复判为 NFR)

Maturity marking

Lightweight three-level marking,advisory and non-blocking：

Level	Meaning	Characteristics
idea	Feature scope not converged	Initial brainstorming just completed, MoSCoW not yet determined
draft	Basically clear but with open questions	Main features identified, some details pending clarification
ready	Can enter keel	Passes the ready gate check

Assumption challenge (product level, must be executed before ready assessment)

All product outputs entering ready assessment must execute this (both the PRD path and the idea→brainstorm path trigger it). Review the validity of assumptions for global requirements:

#	Challenge question
1	Do the identified user roles actually exist in the target user group?
2	Does each FR solve a root problem or a surface symptom?
3	What have we decided not to do? Would excluding/including it change the value proposition?
4	Which features are truly independent, and which only have value as a whole?

Record the challenge conclusions in the "Assumption Challenge" section of index.md (confirmed assumptions / assumptions needing revision / scope adjustments).

ready gate check (advisory)

• At least 1 primary user role is defined
• Scope boundaries are defined (included/excluded)
• Each FR-XX has at least 1 acceptance intent
• No blocks with status=pending (all at least clarified)
• Assumption challenge has been executed, and there are no unresolved "assumptions needing revision"

If not satisfied, annotate the missing items in index.md; the user may choose to still enter keel.

keel bridging

Bridging timing

When the overall maturity=ready, proactively recommend:

需求包已就绪（maturity: ready），建议运行：
/requirements --from-prd docs/prd/requirements/index.md

Bridging is also possible when maturity is draft, but the user must be reminded that open questions may affect subsequent quality.

Bridging principles

• Requirement filesdo not assign F/US/AC numbers, numbering authority belongs to keel
• FR-XX/NFR-XX are the unique identifiers of the product stage; after entering keel they are mapped to F-XXX
• Requirement files are stored in docs/prd/, not written to docs/devdocs/
• Passed into keel as small documents: index.md provides the global view, and each FR-XX corresponds to an independent feature domain

Orchestration specification (sub-agent scheduling)

Task tool / sub-agent delegation rules: see skills/shared/constraints.md § 3

Division of labor	PRD private constraints
Delegation	prd starts prd-parser and prd-brainstorm via Task (block by block), and receives YAML summaries
self-executed	Cross-block synthesis, index.md generation, and clear cleanup are executed by prd itself
summary passing	Only YAML summaries + file paths + new ID lists are passed between stages; the orchestrator Agent does not readthe full output document contents of sub-skills to make orchestration decisions
exception fallback	When a sub-Agent returns status: failed + blockers , display the blocking items and ask the user to fix/skip/terminate;do not read documents on your own to troubleshoot
context isolation	Each sub-Agent reads the prerequisite files it needs on its own (from the docs/prd/ file system), without relying on the orchestrator Agent to pass full text

File output paths

docs/prd/
+-- chunks/                     <- PRD 原文完整文本化副本（仅 prd-parse 路径产生）
|   +-- FR-XX-<topic>.md
|   +-- NFR-XX-<topic>.md
+-- requirements/               <- brainstorm 澄清后的结构化需求
|   +-- index.md                <- 本需求总纲（含跨块合成结果 + keel 映射表）
|   +-- FR-XX-<topic>.md
|   +-- NFR-XX-<topic>.md
+-- source/                     <- 原始文件来源记录（.gitignore 排除）
    +-- manifest.md
    +-- original-prd.md

Template：

• Master outline template:templates/requirements-index-template.md
• Requirements sub-file template:templates/requirements-item-template.md

Authoritative model

docs/prd/requirements/index.md is the sole authoritative source for the following information of the current requirement: requirements list, cross-block synthesis results (terminology/assumptions/cross-cutting NFRs/conflicts), assumption challenges, and keel mapping. Each FR-XX/NFR-XX sub-file is the content authority for the corresponding requirement item.

• FR/NFR are numbered sequentially within the current requirement, two digits (FR-XX), and once assigned are not reused within this requirement.
• New requirements restart from FR-01 — product-stage numbering is a temporary identifier that becomes void once mapped into keel, and does not need to be globally unique across requirements (relying on thenew requirement gateto ensure the old scaffold has been cleaned up).
• For the mapping state machine (active/outdated/remapped/removed, authoritative row), see prd-mapping-status.md。

Constraints

Orchestration constraints

• The pipeline is only responsible for routing, connecting, and cross-block synthesis, and does not replicate the exploration/parsing logic of atomic skills
• The brainstorm and prd-parser stages must be delegated to the corresponding skills for execution
• The information passed between stages is limited to: YAML summaries, file paths, and new ID lists

Single-requirement scaffold constraints

• The gate check must be executed before creating a new requirement(when index.md already exists, ⚠️ choose one of three; if unconfirmed ⛔ do not overwrite)
• Do not maintain a cross-requirement global index / ID registry / archive / iteration chain
• Before clear deletes anything, it must output the scope + impact dry-run; orphaned/unsynced items are not deleted by default

Auto-detection constraints

• Prefer to automatically determine using input length + structural features, and only ask when it cannot be determined
• AskUserQuestion at most once to confirm routing, with no open-ended questions

Maturity constraints

• Maturity markers are advisory and do not hard-block the flow
• When maturity=idea, do not proactively recommend keel connection

Numbering constraints

• FR-XX/NFR-XX are the only IDs in the product stage; do not assign F/US/AC numbers

Skill collaboration

Scenario	Orchestrated Skill chain
Brainstorming	New gate → prd-brainstorm → index generation → ready check
PRD parsing	New gate → prd-parser → block-by-block prd-brainstorm → cross-block synthesis → index generation → ready check
PRD update	prd-parser (re-parse) → fingerprint comparison → brainstorm only outdated blocks → index update
Cleanup and wrap-up	clear (dry-run → orphan interception → ⚠️ confirmation → delete), usually delegated by the final step of pipeline close
keel handoff	When ready, recommend requirements --from-prd

Sub-Agent summary format

yaml-summary-v1 envelope: see skills/shared/constraints.md § 2

summary.details private field：

Field	Value range / example
index_path	docs/prd/requirements/index.md
mode / maturity	brainstorm | prd-parse | clear / idea | draft | ready
functional_count / nonfunctional_count	Functional / non-functional count
clarified_count / open_questions	Clarified block count / open question count
ready_checks_passed / ready_checks_total	Ready checks passed / total
clear_removable / clear_orphans	clear mode only: safe to clean / orphan unsynced item count

PRD status determination：success = all blocks processed and index.md generated (clear mode: cleanup completed or dry-run report generated);partial = partially processed blocks (user interruption or some blocks failed);failed = critical step failed (e.g., PRD cannot be parsed).

Artifact fields：output_files list index and FR/NFR files;new_ids.requirements record FR-09~FR-14, NFR-04~NFR-05 such newly added numbers;next_recommended can point to requirements --from-prd docs/prd/requirements/index.md。

Next steps

After pipeline completion, give suggestions based on maturity:

• ready → recommend /requirements --from-prd docs/prd/requirements/index.md
• draft → prompt the open question list, suggest supplementing before handoff, or the user chooses to directly enter keel
• idea → suggest continuing /prd brainstorm deepen exploration