SKILL.md 8.19 KB

Edit Raw Blame History



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，至少包含：


WHY（a/b/c/d/e）
HOW（组织层与执行层机制）
WHAT（可观察交付）
范围边界（Scope In / Scope Out）
质量与风险门禁（阻塞、失败关闭、回流）
数据与契约边界（Node/Edge 级）
验证链路（可复查证据 + 回放）


执行前置（强制）

先校验是否已有相关 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 类验收：


目标态（成功）：关键输出全部就绪。
边界态（阻塞）：明确阻塞原因和恢复条件。
失败态：失败归因完整且可回放。

例：


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


4. 写作流程（Code-Act Loop）

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


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 无验收指标、无失败态定义。
将假设写成事实，不给来源。
历史失效复发却只做局部修复不更新通用规范。