---
name: project-brd-planning
description: |
  生成/更新 BRD（Business Requirements Document）草案，约束 4 层/5 层 Graph 体系的需求边界与价值目标。
tags:
  - planning
  - graph
  - brd
description_long: |
  适用于：首次建项、已有需求的补充、需求变更触发重审。
  目标是把“原始意图”转成可开发、可验证、可追溯的 BRD，且支持两层 Graph（Org Graph + Work Graph）组织化治理。
version: 1.1.1
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [planning, brd, graph-management]
---

# SKILL：project-brd-planning（v1.1.1）

## 适用场景
- 新建项目需求、已有需求重构、需求变更重审。
- 需要把单点任务变成“可持续治理”的 BRD（尤其长程任务、多个 Loop、组织层规范沉淀）。

## 关键输入
- 用户的一句话/短文本需求。
- 可复用资料：历史 BRD/PRD/SDD、事故记录、缺陷样例、现网约束、组织角色边界。
- 文档与执行语境（仓库、空间、运行方式）。
- 明确的“成功率/时间/质量”约束（若无则标为假设）。

## 输出目标（硬性要求）
产出一份可直接监督的 BRD，至少包含：
1. **WHY**（a/b/c/d/e）
2. **HOW**（组织层与执行层机制）
3. **WHAT**（可观察交付）
4. **范围边界**（Scope In / Scope Out）
5. **质量与风险门禁**（阻塞、失败关闭、回流）
6. **数据与契约边界**（Node/Edge 级）
7. **验证链路**（可复查证据 + 回放）

---

## 执行前置（强制）
- 先校验是否已有相关 skill 文档更新需求；如规则变化，先更新本 skill 或调用治理 skill 做规则确认。
- 先区分“事实 / 设计决策 / 假设 / 阻塞未知”。
- 所有事实结论必须能追溯到来源；无法追溯的内容不得写成事实。

---

## 1. 产出结构（强制顺序）

### A. WHY（为什么）
按以下 5 个子问题完整回答：
- **(a) 我们为什么要做这件事情？**（问题、重复性风险、回归成本）
- **(b) 它的目的是什么？**（预期可观察结果）
- **(c) 它为谁解决什么价值问题？**（角色 × 痛点 × 可验证收益）
- **(d) 与历史失效对齐吗？**（同类缺陷样本映射，源头归因）
- **(e) 为什么是“组织级 Graph”而不是“单任务 Loop”？**（Loop 的边界、Graph 的治理优势）

每个子问都必须附：
- 证据来源（文档路径/会议记录/日志/历史版本）；
- 受益对象；
- 未做的后果。

### B. HOW（怎么做）
以机制描述为核心，不写实现细节。
- 写明两层图分工：
  - **Org Graph**：组织边界、角色、规则、分发、阻塞/回流、状态约束。
  - **Work Graph**：任务图的执行单元、并行/串行、边界契约、重放。
- 说明动态入口类型（Existing-Docs / Existing-Code / New Project / Refactor）。
- 说明至少一个可用的调度策略（Loop 与回流关系）。
- 写入 14-Step 映射（可直接抄模板）：
  1) 线性脚本退化识别
  2) 每条依赖问“下游是否消费上游输出”
  3) 节点合同（输入/输出/schema）
  4) 边当数据契约
  5) 并行扇出
  6) barrier 仅用于全局同步点
  7) split→fan-out→reduce→synthesize
  8) 条件路由（code-level）
  9) verifier 校验器
  10) 节点隔离与故障隔离
  11) 受控循环（loop-until-dry）
  12) 任务按认知负载分层模型
  13) 拓扑即成本（可解释同步选择）
  14) 自主组织化（动态生成 workflow）
- 对应到 BRD 中“组织化能力”与“执行能力”双闭环。

### C. WHAT（做成什么样）
- 用“可观察结果”写，不要写“打算改代码怎样”。
- 至少覆盖：
  - 两层图是否可用；
  - 约束是否可回放；
  - 失败归因是否可追溯；
  - 同类问题是否可在规范层先纠偏。

### D. 组织级契约（Node / Edge / Trace）

#### 节点硬约束（Work 节点）
- 必填字段：`node_id, owner, owner_role, input_ref, output_schema, deadline, retry_policy, failure_mode`
- 要求：单一职责、输入输出明示、异常状态可映射。

#### 边硬约束（Work 边）
- 必填字段：`from_node, to_node, payload_schema, validator, propagation_rule, rollback_policy`
- 条件：无 schema 不允许流转到下游。

#### 触发与结果约束
- 触发需写原因、前置依赖状态、阻塞清单。
- 输出需含 `trace_id, source_hash, timestamp, state, evidence`。
- 失败包缺失时必须进入阻塞，不得流转开发。

---

## 2. 组织治理能力（必须写进 HOW/WHAT 的标准段）

### 2.0 组织语义模型（harness-loop-graph）
- **Harness**：运行环境层（工具、权限、执行上下文、工作目录）。
- **Loop**：适合“单路径重复”：Plan→Exec→Check→Repeat 的稳定节拍。
- **Graph**：适合“分叉协作”：节点是专责角色，边是交接/路由，State 是共享记忆；条件边基于 state 字段决定分支。
- 规则：不是二选一，而是分层；Loop 可内嵌于 Graph，但 Graph 不应被无脑替代 Loop（不分叉就别造图）。

### 2.1 图反模式（写入 Quality Gate）
- **无 Merge Point**：并行后未汇聚归并，导致状态分歧。
- **无 Verifier**：路由后缺检验，错误会扩散。
- **无循环上限**：条件循环无结束分支会死循环。
- **过度分叉**：无必要并发造成成本、推理抖动和状态冲突。

### 2.2 治理优先级（必须写进 HOW/WHAT）
- **同类缺陷治理优先级高于局部修复**：
  - 发现复发缺陷后，先更新通用规范；再允许局部任务修复。
- **失败关闭**：
  - 阻塞未知/边界争议/权限不确定必须标为 blocked。
  - blocked 条目需给恢复条件，未恢复前不流转开发。
- **trace 回放**：
  - 每个失败提供归因（Planning/Code/QA/External）；
  - 能从 BRD 追到单次失败处理的决策依据。

---

## 3. 验收与自测（必须给到可测项）
- 至少 3 类验收：
  1. 目标态（成功）：关键输出全部就绪。
  2. 边界态（阻塞）：明确阻塞原因和恢复条件。
  3. 失败态：失败归因完整且可回放。

- 例：
  - WHY(a)-(e) 每条均有来源；
  - HOW 有 Org/Work 分工、14-step 映射与 barrier/route 规则；
  - WHAT 有节点边契约字段；
  - Scope Out 与阻塞项完整。

---

## 4. 写作流程（Code-Act Loop）
1. **事实裁决**：列事实/假设/未知。
2. **组织化切片**：以“价值单元”而非组织职能先切段。
3. **BRD 初稿**：按标准模板输出。
4. **自审 + 失败关闭**：若任一必填缺失，返回待修订，不流转下游。
5. **草稿与文档回读核对**：本地草稿与目标文档版本一致性检查。

---

## 5. 复用模板（给新项目可直接套用）
- 先写一句“项目一句话目标”。
- 然后按 Why(a~e) 逐条填来源。
- 再写 HOW，强制插入 14-Step 的 1~3、4~8、9~14 摘要。
- 再写 WHAT，包含 node/edge 约束与失败关闭。
- 最后写 Success Criteria、Scope、Risk 与阻塞条目。
- 若任务存在并发/分支，按组织角色映射补一段（例如 Mayor/Polecat/Refinery/Witness 或等价组织角色），并给出角色职责边界。

---

## 6. 质量自查（产出前）
- [ ] WHY 包含 (a)(b)(c)(d)(e) 并可溯源。
- [ ] HOW 以机制为主，且体现 Org/Work 双层边界。
- [ ] WHAT 可测且不写实现细节。
- [ ] node/edge/trace 约束字段齐全。
- [ ] 同类缺陷有“先更新规范后局部修复”的规则。
- [ ] 阻塞点有恢复条件，不得含“待定并继续执行”。
- [ ] 显式标注 Scope In/Scope Out。
- [ ] 与 PRD/SDD 接口字段（至少目标字段）已定义。
- [ ] 对外部文档/代码证据的读取与版本一致性已说明。

---

## 6. 成功判定
- 输出该 BRD 后，下一步可自动触发 PRD 流程。
- 若有阻塞 unknown，结论是 `需澄清` 并且 blocked 项目完整。
- 若无阻塞且自检全过，结论是 `可立项`。

## 7. 典型反例（避免）
- 只有任务清单，无 WHY/HOW/WHAT。
- HOW 写成“如何写代码”。
- WHAT 无验收指标、无失败态定义。
- 将假设写成事实，不给来源。
- 历史失效复发却只做局部修复不更新通用规范。