project-document-discovery

project-document-discovery — SKILL.md

**变体：**标准 · **使用时机：**受调用后，将项目构想转化为与项目规模相称、按能力划分范围的文档计划；返回包含三个键的 JSON（capability_map + product_capabilities + manifest）；控制权返回调用方。

概述

给定一个软件／产品项目构想，此技能将判断项目上线所需的文档，以及编写每份文档需要什么——包括负责角色、工具／提供方、技能，以及该文档依赖的其他文档。它仅负责发现：选择文档集合并说明每份文档将如何产出，而不涉及如何编写文档（这由单独的逐文档编写技能负责）。指导原则是与项目规模相称——文档集合的规模应与项目相符。

此技能在单次模型调用中分两个明确的内部阶段运行：

• **阶段 A — 分类 + 识别：**从 10 个维度簇对项目进行分类 → 识别产品的不同能力领域（4 信号算法 + 规模测试）→ 生成 capability_map JSON 和 product_capabilities 列表。
• **阶段 B — 扩展生成清单：**根据分类标记选择共享文档 → 根据能力列表生成各能力对应的文档条目（扩展规则）→ 添加 DAG 边 → 自检。

输出：包含三个键的 JSON {capability_map, product_capabilities, manifest}。

何时启用

• ✅ 在产出任何文档之前，确定新项目需要哪些文档（绿地项目）。
• ✅ 修订项目变更对应的文档计划（新功能、方向调整、新的合规要求、项目类型转变）——当 capability-map.yaml 和 manifest.yaml 已存在时，使用修订模式。
• ✅ 生成按能力划分范围的清单，供后续阶段读取并据此产出文档。

请勿在以下情况下启用：

• 编写或套用特定文档模板——使用逐文档编写技能及内容／模板技能。
• 发现构建阶段的工程团队构成——这是基于最终文档开展的另一项后续分析。
• 项目已有经确认的文档集合，且当前不涉及任何变更。

工作流

有两种模式：绿地模式依次运行阶段 A（步骤 1–3）和阶段 B（步骤 4–9）。修订模式（已有 capability-map.yaml + manifest.yaml + 变更请求）运行下文的迭代／修订方法，而不是重新推导。

---

阶段 A — 分类 + 识别

步骤 1：对项目进行分类，覆盖 10 个维度集群，并编写 prior_art_triggers

阅读 idea.md。加载 references/classification-schema.md（基于依据的 v2 字段／枚举参考及触发器公式）。将项目划分到 10 个维度集群中 → 生成一个 capability_map JSON 对象（每个集群作为顶层键），然后编写 prior_art_triggers。

集群键	分类内容
archetype	项目原型（主要 + 次要）+ 生命周期阶段
domain	业务领域 + 受众（b2c / b2b / b2b2c / developer / internal）
regulatory	是否适用任何监管制度 + 按行业列出的具名框架
scale	并发量、吞吐量、实时性等级、可用性目标、一致性、地理分布、数据量
security	ASVS 等级、数据敏感度、身份验证／授权模型、攻击面
integrations	是否集成第三方服务（预期情况）+ 复杂度 + 类别／模式
ui	是否有 UI + 复杂度 + 目标用户 + 无障碍性
data_ml	数据管道 + ML 参与情况 + 治理
infrastructure	部署模型 + 计算范式 + 灾难恢复／可观测性
business	商业模式 + 平台形态（类型）+ OSS
prior_art_triggers	应用分类方案参考中的公式，编写 10 个布尔门控项，依据刚生成的分类结果计算——不得省略。

capability_map 采用严格校验（以 schemas/capability-map.schema.json + reviewing-document-discovery 为唯一依据）：未知的集群字段会被拒绝；[required]／[trigger] 输入字段（上方加粗标示且在参考中注明的字段）必须存在；枚举标记必须原样输出（字符完全一致，不得添加空格）。prior_art_triggers 由模型编写，并由验证器保证——确定性门控（scripts/validate.py）会重新计算每个公式，并在发现任何不匹配时失败，因此错误标记会在 in_dev 自我修复阶段显现，绝不会被静默忽略。每个集群的字段、基于依据的枚举标记集合以及 10 个触发器公式，请参阅 references/classification-schema.md。

---

第 2 步：识别产品的不同能力领域

在此步骤开始时加载 references/reference-architectures.md（渐进式披露——与阶段 B 中的 document-type-catalog.md 使用相同模式）。该文件包含 4 信号算法、参考架构表（10 个领域 × 规范 L1 能力领域）、三项规模测试、边界契约填写指南和能力数量指南。

按顺序应用参考文件中的 4 信号识别算法：

1. 信号 1——领域参考架构（置信度最高）：在参考架构表中查找 domain.primary；采用并精简规范分解。如果领域较新，则继续应用信号 2–4。
2. 信号 2——关键领域事件：从 idea.md 中提取主要状态转换（例如“订单已下单”）。每个转换都是一个边界——左侧领域负责转换前发生的事情，右侧领域负责转换后发生的事情。
3. 信号 3——核心领域名词：提取主要名词并将其分组成实体簇。每个实体簇对应负责管理这些实体的能力领域。
4. 信号 4——待完成的工作：映射 idea.md 中的用户工作。每个不同的工作簇对应一个能力领域。

为每个识别出的能力领域填写完整的边界契约（所有必填字段，以及 idea.md 中存在的所有可选字段）：

• 必填： id（唯一的 kebab-case 标识符）、name、scope（简洁，1–3 句话：说明负责和不负责的内容——必须包含否定部分）、owns（无所有者的能力可以留空：纯 UI / 网关 / 分析 / 编排）、has_ui、has_api、has_persistence
• 可选： subdomain（core / supporting / generic）、parent、refs（点号表示法：{capability-id}.{entity-name}）、publishes / consumes（点号表示法：{capability-id}.{event-name}）、entry_points、exit_points、depends_on、ui_complexity（simple / moderate / complex / consumer-grade）、impl_complexity（simple / moderate / complex——后端/算法复杂度；决定是否需要 technical-design-{id}）、has_model（布尔值，默认 false——该能力训练或提供 ML 模型；决定是否需要 model-card-{id}，并选择系统级 eval-plan）、notes
• 必须省略： level、status、superseded_by、merged_into——由 Python 注入。

有关点号表示法约定和各标志的填写指南，请参阅 references/reference-architectures.md 中的边界契约填写指南。

---

第 3 步：应用能力数量检查和规模测试

对每个 L1 候选项应用全部三项规模测试（见参考文件）：

1. 单团队测试：一个跨职能团队可以端到端地负责它。
2. 单一变更原因测试：该能力的变更原因恰好只有一个业务原因。
3. 撰写轮次测试：范围说明中不需要用“和”连接两个不相关的关注点。

**如果候选项未通过任意一项测试：**拆分它。**如果仅未通过测试 3：**添加 L2 子能力（parent: {l1-id}），而不是完全拆分。

**能力数量目标：**4–10 个 L1 领域。少于 4 个 = 分解不足；多于 10 个 = 分解过度（合并紧密耦合的领域，或添加 L2 子能力，而不是增加更多 L1）。

---

阶段 B——扇出清单

步骤 4：生成共享文档条目

读取阶段 A 中的 capability_map。根据分类标志生成共享文档：

文档	条件	生成者	类型
prd	始终	idea-strategist	prd
architecture-doc	始终	systems-architect	architecture-doc
design-system	任一能力的 has_ui: true	ux-designer	design-system
user-flows	任一能力的 has_ui: true	ux-designer	user-flows
system-wireframes	任一能力的 has_ui: true	ux-designer	wireframes
release-runbook	archetype.primary 不在 {cli-tool, library-sdk} 中（由服务/应用运行；CLI 和库是分发而非部署）	engineer	release-runbook
eval-plan	任一能力的 has_model: true	engineer	eval-plan

在此步骤开始时加载 references/document-type-catalog.md。添加分类标志触发的所有领域覆盖文档：

• regulatory.applies: true → 添加法律治理覆盖文档
• data_ml.has_data_pipeline: true → 添加数据/ML 覆盖文档（datasheet、data-lineage、data-contract、data-dictionary）。此处不要添加 model-card 或 eval-plan——它们是根据每项能力的 has_model 标志选择的规则（步骤 5 的 model-card-{id} + 本步骤表格中的系统级 eval-plan），而非覆盖文档。
• security.pii_involved: true + 合规要求 → 添加安全/合规文档

---

步骤 5：生成每项能力的文档条目（扇出规则）

对于 product_capabilities 中的每个有效能力领域（status == active 或无 status 字段），生成每项能力对应的文档条目：

扇出规则	条件	文档 id	类型	capability
功能规格	始终	feature-spec-{id}	feature-spec	docs
数据模型	has_persistence: true	data-model-{id}	data-model	docs
API 规格	has_api: true	api-spec-{id}	api-spec	docs
技术设计	impl_complexity 在 ["moderate", "complex"] 中	technical-design-{id}	technical-design	docs
模型卡	has_model: true	model-card-{id}	model-card	docs
用户流程	has_ui: true	user-flows-{id}	user-flows	design
线框图	has_ui: true	wireframes-{id}	wireframes	design
高保真设计	has_ui: true 且 ui_complexity 在 ["complex", "consumer-grade"] 中	hi-fi-{id}	hi-fi	design

将每个文档条目的 scope 字段设为该能力的 id（每项能力对应的条目），或 "system"（共享条目：prd、architecture-doc、design-system、system-wireframes、user-flows、release-runbook、eval-plan）。

每个清单条目必须包含：id、title、type、scope、capability（标量字符串：文本类文档为 "docs"，线框图/高保真设计为 "design"）、archetype（生成者的原型）、roles（恰好两个角色 id，顺序为 [author, reviewer]——工程师/策略师使用 [document-author, document-reviewer]，设计师使用 [designer, design-reviewer]）、depends_on（在步骤 6 中填写）、skills（此文档类型的撰写和审阅技能 id，两者都要包含——例如 [authoring-prd, reviewing-prd]——从 references/manifest-schema.md 第 4 节获取）、account（发现阶段为 null）以及 status（greenfield 项目设为 "active"）。

步骤 6：设置 depends_on 边（生产环境 DAG）

为每个文档条目附加 depends_on。从 references/document-type-catalog.md 获取每种类型的规范边，然后裁剪为本项目实际包含的文档（删除指向缺失文档的边）。

每项能力的文档 DAG 边（在目录边之外额外应用）：

文档	depends_on 边
feature-spec-{id}	[prd] + [feature-spec-{d} for d in cap.depends_on]
data-model-{id}	[feature-spec-{id}]
api-spec-{id}	[feature-spec-{id}] + 如果 has_persistence，则为 [data-model-{id}]
technical-design-{id}	[feature-spec-{id}, architecture-doc] + 如果 has_api，则为 [api-spec-{id}] + 如果 has_persistence，则为 [data-model-{id}]
user-flows-{id}	[user-flows, feature-spec-{id}]
wireframes-{id}	[system-wireframes, feature-spec-{id}, user-flows-{id}]
hi-fi-{id}	[wireframes-{id}, design-system] + 来自 cap.depends_on 的跨能力 hi-fi 边
system-wireframes	[design-system, user-flows]
user-flows	[prd]
design-system	[prd, architecture-doc]
release-runbook	[architecture-doc] + 如果集合中存在 [test-plan]
eval-plan	[prd]
model-card-{id}	[eval-plan] + 如果 has_persistence，则为 [data-model-{id}]

验证组装后的（裁剪后）图无环——目录边已预先验证为无环；裁剪不会引入环；这是安全检查。

---

步骤 7：研究 / 针对未知项补建技能

对于你不熟悉的文档类型、原型或领域，先研究它（或为其补建技能），再进行归类——绝不要猜测其用途、产出方或依赖项。

第 8 步：填充清单元数据部分

加载 references/manifest-schema.md。根据整理好的文档集推导并填充全部五个元数据部分。不得将任何部分留为 []。

capabilities: — 从 references/manifest-schema.md 第 2 节逐字复制：

• 始终包含 docs 能力条目。
• 仅当 Phase A 中 ui.has_ui: true 时，才包含 design 能力条目。
• 不要包含任何其他能力（auth、ci、vcs、storage 等）——这些属于构建级别，不在发现范围内。
• 每个条目均设置 selected_provider: null、account: null、status: "unassigned"。

roles: — 根据文档类别推导作者/审阅者 PAIR（角色仅代表人物设定——不包含 skills/tools 字段）：

• 如果任何文档的 archetype: "engineer" 或 archetype: "strategist"，则包含 document-author 和 document-reviewer 两个角色（从 references/manifest-schema.md 第 3 节完整复制定义）。
• 如果任何文档的 archetype: "designer"，则包含 designer 和 design-reviewer 两个角色（从 references/manifest-schema.md 第 3 节完整复制定义）。
• 每个角色条目均设置 resolved_id: null 和 match_status: null（由审批关卡解析）。

skills: — 合并所有文档条目中 skills 数组的内容，然后添加：

• deep-research（category: research）——始终添加
• external-content-sanitizer（category: utility）——始终添加

去重。每项技能均设置 version: null、source: null、resolved_id: null、match_status: null（发现阶段；由审批关卡解析）。为每项技能（无论是规范技能还是自定义技能）编写 purpose（一到两句话，说明该技能必须为本项目完成的任务），并填写非空的 requirements 列表（可逐项核对、以能力为粒度的陈述，供审阅者与已安装的技能进行比对）——编写要求请参见 references/manifest-schema.md 第 1 节。根据 references/manifest-schema.md 第 1 节中的命名规范，从 id 推导 category——优先采用推荐词汇表中的值（authoring、reviewing、research、orchestration、utility、ops、testing、reference/library）；若均不适用，可使用自由文本。同样，tool.type 优先采用 web-search、file-read、file-write、code-exec、api-call、browser、mcp、database、shell、messaging、email、queue。

tools: — 根据文档集，按照 references/manifest-schema.md 第 5 节推导：

• 始终包含 file-read 和 file-write。
• 如果文档集中有任何文本类型的文档，则包含 web-search。
• 如果文档集中有任何设计类型的文档（wireframes、hi-fi、design-system、user-flows），则包含 browser。

amendments: — 全新项目输出中始终为 []。

---

步骤 9：自检（文档计划的完成定义）

返回输出前，请确认计划通过以下 14 项：

1. 比例适当——针对项目的规模和风险，既没有选得过多，也没有选得过少。
2. 包含关键文档——集合中包含 PRD / 功能规格（对于 UI 产品，包含设计文档）。
3. 每份文档都有生产要求——每份文档都有作者和审核者的 roles 配对（顺序为 [author, reviewer]，与原型类型相符）、工具/提供方，以及编写和审核所需的 skills。
4. 每份文档都有 depends_on——每份文档都包含经过精简的 depends_on。
5. 无环 DAG——组装后的（精简）图不存在环。
6. 无孤立文档——每份中间文档都为其他文档提供输入，或由其他文档提供输入；叶子交付物（LICENSE、CHANGELOG、SECURITY.md、README）若 depends_on: []，则不受此限制。
7. 不凑数——不包含项目不会使用的文档。
8. 保留开放性——对无法识别的类型进行研究或构建，不凭空猜测。
9. （仅限修订）变更范围与修改内容一致——仅修改已更改/新增的文档及其 DAG 边。
10. 能力领域：识别出 4–10 个 L1 领域；每个领域都通过全部三项规模测试。
11. 各能力条目：每项启用的能力都有 feature-spec-{id}；扇出标记（has_ui、has_api、has_persistence）与实际生成的各能力文档条目一致。
12. 清单输出结构——返回的 JSON 包含 "manifest" 键（而非根级文档列表）；每个文档条目都有 type 和 scope 字段。
13. 填充元数据部分：capabilities: 包含 docs（始终包含）和 design（若 ui.has_ui: true）；不包含构建级能力。roles:、skills:、tools: 和 amendments: 均存在，且都不为空。roles: 包含每种已出现原型类型的完整作者/审核者配对（若存在工程师/策略师文档，则包含 document-author + document-reviewer；若存在设计师文档，则包含 designer + design-reviewer），且每个角色条目都是纯角色设定（不包含 skills/tools）。每个技能条目都有 version: null、source: null、已填写的 purpose 和非空的 requirements 列表；每个技能和角色条目都输出 resolved_id: null 和 match_status: null。
14. **所有文档条目都包含 capability 标量：**每个文档条目的 capability 都是 "docs" 或 "design"（字符串标量），而不是 capabilities: [...]（数组）。

返回前修复所有未通过的项目。

---

迭代 / 修订（根据变更重新调整现有计划）

收到现有的 capability-map.yaml + 现有的 manifest.yaml + 变更请求时，对差异进行分类并应用——不要重新推导计划。

修订时会同时收到这两个文件作为上下文——完整的现有能力状态和现有文档清单，而不只是变更请求。这样可以让差异仅针对需要更新的内容。

变更类型分类：

类型	描述	结构性变更	人工审核
T1	FIELD_ADD：为现有记录新增可选字段	否	否
T2	FIELD_UPDATE：更新现有记录中的非身份字段	否	否
T3	RECORD_ADD：向列表中新增能力领域	否	否
T4	CAPABILITY_SPLIT：将一个领域拆分为两个	是	是
T5	CAPABILITY_MERGE：将两个领域合并为一个	是	是

**仅允许增量式变更（T2 禁止的修改）：**不得更改 id 和 name；不得移除 owns 项；不得将 has_ui、has_api、has_persistence 从 true 改为 false；列表字段（refs、publishes、consumes、entry_points、exit_points、depends_on）只能追加。

双提示词调度：

1. **提示词 A — 分类：**接收现有的 capability-map.yaml + 现有的 manifest.yaml + 变更请求文本 → 返回 {change_type: T1|T2|T3|T4|T5, capabilities_affected: [...], reason, confidence}。
2. [GATE] 如果 change_type in {T4, T5} 或 confidence != "high"：先提交人工确认，再继续。
3. **提示词 B — 执行：**接收受影响的能力记录 + 变更请求 → 返回 {records: [updated/new CapabilityRecord, ...]}。模型必须省略 level、status、superseded_by、merged_into——这些字段由 Python 注入。

**按类型路由文档影响：**T1 = 不变更扇出；T2 = 修订 feature-spec-{id}（+ 若扇出标志从 false 变为 true，则添加新的文档条目）；T3 = 为新能力添加完整文档集 + 修订 prd；T4/T5 = 将旧文档标记为已取代，为新能力添加完整文档集，修订 prd，并级联更新 depends_on/consumes/refs 中包含旧 ID 的能力。

规则

硬性规则（绝不违反）：

• **仅做发现。**确定哪些文档以及产出这些文档需要什么。绝不撰写或套用模板生成文档。
• **按比例调整，绝不采用固定分类法。**根据项目原型确定文档集规模；精简项目只需少量文档。
• **保留承重文档。**不得为了显得精简而删减 PRD / 功能规格（以及 UI 设计文档）。
• **依赖关系必须构成 DAG。**方向为需求 → 设计 → 交付 → 文档；不得有循环。
• 优先使用开源工具和提供商（开源 → 免费 → 付费）；优先选择本地运行 / 可自托管方案。
• **遇到未知类型时进行调研 / 在缺口处打造；**绝不臆造其用途。
• **修订仅允许增量式变更。**修订模式下，不得更改身份字段、移除实体或降低扇出标志。结构性变更应使用 T4/T5（需人工审核）。

偏好（可覆盖）：

• 按生命周期阶段分组所选文档集。
• 将产出方命名为角色类型；当使用者采用该模型时，使用 archetype × domain。
• 对于易变细节（API 端点、架构），优先采用生成并链接，而不是在正文中重复。

易忽略之处

• 在小型项目上采用过于庞杂的固定分类体系。 原因：跳过了第 1 步原型分类。解决方法：先分类，再按分类确定规模。
• 为了显得精简而删掉关键文档。 原因：省略了 PRD/功能规格说明。解决方法：保留关键文档层级；精简可选层级。
• 偏离方向，开始撰写文档。 原因：列出文档的各个章节。解决方法：只说明是哪种文档，以及编写它需要什么。
• 出现循环依赖。 原因：PRD 的 depends_on 指向架构。解决方法：依赖关系只能是需求 → 设计 → 交付 → 文档。
• L1 能力超过 10 项。 原因：将每个名词都视为独立领域。解决方法：合并紧密耦合的领域；添加 L2 子能力，而非增加更多 L1 能力。
• 忘记在 scope 中写明否定条款。 原因：只写能力的作用。解决方法：每个 scope 都必须以“does NOT…”结尾——它定义了边界。

反模式

• “每个项目都需要完整的 SDLC 文档集。” 不需要，应根据原型确定文档集。
• “决定文档集时，我也会概述每份文档该怎么写。” 这是文档撰写，超出范围。
• “我不认识这种文档类型，就猜一个。” 应改为调研，或在存在空缺时自行创建。
• “跳过 PRD，我们会在代码中确定功能。” 必须先在文档中定义功能。
• “多加几份文档以防万一。” 这是凑数；按比例确定的文档集完整后就应停止。
• “修改时从头重新运行发现流程。” 修改只需重新调整差异部分；不要重新推导。

输出

此技能返回一个包含三个键的 JSON 对象。此技能不会写入文件。调用方根据此对象写入两个文件：

• <scope_root>/capability-map.yaml — 使用键 capability_map + product_capabilities
• <scope_root>/manifest.yaml — 使用键 manifest（全部五个部分）

scope_root 是调用方提供的上下文。此技能不会假设或推导该值。

返回的三键 JSON 对象：

{
  "capability_map": {
    "archetype": { "primary": "web-app", "secondary": ["api-service"], "lifecycle_stage": "invest" },
    "domain": { "primary": "e-commerce", "audience": "b2c", "consumer_facing": true },
    "regulatory": { "applies": true, "frameworks": ["gdpr", "pci-dss"], "data_privacy": { "gdpr": true }, "financial": { "pci_dss": true } },
    "scale": { "concurrency": "high", "throughput": "high", "real_time": "soft", "availability_target": "99.9", "consistency": "strong", "geo_distribution": "single-region", "data_volume": "medium" },
    "security": { "asvs_level": 2, "data_sensitivity": { "level": "confidential", "has_pii": true, "has_payment_data": true }, "auth_complexity": "mfa", "authz_complexity": "rbac" },
    "integrations": { "expected": true, "complexity": "moderate", "categories": { "payments": true } },
    "ui": { "has_ui": true, "complexity": "consumer-grade", "target_users": "consumer", "accessibility": { "required_level": "AA" } },
    "data_ml": { "has_data_pipeline": false, "ml_involvement": "none" },
    "infrastructure": { "deployment_model": "cloud", "compute_paradigm": "container", "cloud_providers": ["aws"] },
    "business": { "model": "ecommerce", "platform": { "type": "none" } },
    "prior_art_triggers": { "_derived": true, "code": true, "visual": true, "market_competitive": true, "user_research": true, "security": true, "ml": false, "regulatory": true, "scale": true, "integrations": true, "platform_ecosystem": false }
  },
  "product_capabilities": [
    {
      "id": "catalog",
      "name": "Catalog",
      "scope": "Manages product listings, variants, and pricing; does NOT handle inventory or fulfillment.",
      "subdomain": "core",
      "owns": ["product", "variant", "price"],
      "has_ui": true,
      "has_api": true,
      "has_persistence": true,
      "ui_complexity": "consumer-grade"
    }
  ],
  "manifest": {
    "version": 3,
    "generated_at": "<ISO-8601>",
    "schema": "manifest/v1",
    "documents": [
      {
        "id": "prd",
        "title": "Product Requirements Document",
        "type": "prd",
        "scope": "system",
        "capability": "docs",
        "archetype": "strategist",
        "roles": ["document-author", "document-reviewer"],
        "skills": ["authoring-prd", "reviewing-prd"],
        "depends_on": [],
        "account": null,
        "status": "active"
      },
      {
        "id": "feature-spec-catalog",
        "title": "Feature Spec: Catalog",
        "type": "feature-spec",
        "scope": "catalog",
        "capability": "docs",
        "archetype": "engineer",
        "roles": ["document-author", "document-reviewer"],
        "skills": ["authoring-feature-spec", "reviewing-feature-spec"],
        "depends_on": ["prd"],
        "account": null,
        "status": "active"
      },
      {
        "id": "wireframes-catalog",
        "title": "Wireframes: Catalog",
        "type": "wireframes",
        "scope": "catalog",
        "capability": "design",
        "archetype": "designer",
        "roles": ["designer", "design-reviewer"],
        "skills": ["authoring-wireframes", "reviewing-wireframes"],
        "depends_on": ["system-wireframes", "feature-spec-catalog"],
        "account": null,
        "status": "active"
      },
      {
        "id": "hi-fi-catalog",
        "title": "Hi-fi: Catalog",
        "type": "hi-fi",
        "scope": "catalog",
        "capability": "design",
        "archetype": "designer",
        "roles": ["designer", "design-reviewer"],
        "skills": ["authoring-hi-fi", "reviewing-hi-fi"],
        "depends_on": ["wireframes-catalog", "design-system"],
        "account": null,
        "status": "active"
      }
    ],
    "roles": [
      {
        "id": "document-author",
        "name": "Document Author",
        "goal": "Produce high-quality, evidence-grounded project documents.",
        "persona": "Senior technical writer and engineer with deep domain expertise. Grounds every claim in research or existing project artifacts. Writes for the next engineer, not for the original author.",
        "model": "claude-sonnet-4-6",
        "resolved_id": null,
        "match_status": null
      },
      {
        "id": "document-reviewer",
        "name": "Document Reviewer",
        "goal": "Gate-check project documents against their acceptance bar before they are approved.",
        "persona": "Senior staff engineer acting as an adversarial reviewer. Judges a document against its type's acceptance bar, hunting gaps, unstated assumptions, and unverifiable claims. Grounds every finding in evidence and never rewrites the document under review.",
        "model": "claude-sonnet-4-6",
        "resolved_id": null,
        "match_status": null
      },
      {
        "id": "designer",
        "name": "Designer",
        "goal": "Produce structural, buildable design artifacts grounded in UX research.",
        "persona": "Senior product designer with UX research and interaction-design expertise. Produces design artifacts that engineering can implement directly. Grounds visual decisions in user research and established design systems.",
        "model": "claude-sonnet-4-6",
        "resolved_id": null,
        "match_status": null
      },
      {
        "id": "design-reviewer",
        "name": "Design Reviewer",
        "goal": "Gate-check design artifacts for buildability, coverage, and accessibility before they are approved.",
        "persona": "Senior product-design lead acting as an adversarial reviewer. Judges a design artifact against its type's buildability and accessibility bar, hunting missing states, unbuildable ambiguity, and unguarded flows. Grounds every finding in established UX practice and never redesigns the artifact under review.",
        "model": "claude-sonnet-4-6",
        "resolved_id": null,
        "match_status": null
      }
    ],
    "skills": [
      { "id": "authoring-prd", "version": null, "source": null, "category": "authoring", "purpose": "Author the product requirements document from the approved request.", "requirements": ["evidences the problem with jobs-to-be-done", "defines measurable success metrics", "draws a defensible MVP boundary"], "resolved_id": null, "match_status": null },
      { "id": "reviewing-prd", "version": null, "source": null, "category": "reviewing", "purpose": "Gate-check the PRD for plannability before approval.", "requirements": ["verifies metrics are measurable", "checks the MVP boundary is defensible", "flags unproven claims"], "resolved_id": null, "match_status": null },
      { "id": "authoring-feature-spec", "version": null, "source": null, "category": "authoring", "purpose": "Elaborate a PRD feature into implementable, testable detail.", "requirements": ["specifies observable behavior", "enumerates edge cases", "writes testable acceptance criteria"], "resolved_id": null, "match_status": null },
      { "id": "reviewing-feature-spec", "version": null, "source": null, "category": "reviewing", "purpose": "Gate-check a feature spec for buildability.", "requirements": ["checks behavior coverage", "verifies acceptance-criteria testability"], "resolved_id": null, "match_status": null },
      { "id": "authoring-wireframes", "version": null, "source": null, "category": "authoring", "purpose": "Produce structural low-fidelity wireframes per screen.", "requirements": ["lays out screen regions on a grid", "annotates components and per-screen states"], "resolved_id": null, "match_status": null },
      { "id": "reviewing-wireframes", "version": null, "source": null, "category": "reviewing", "purpose": "Gate-check wireframes for buildable coverage.", "requirements": ["checks every flow screen is covered", "verifies empty/loading/error state coverage"], "resolved_id": null, "match_status": null },
      { "id": "authoring-hi-fi", "version": null, "source": null, "category": "authoring", "purpose": "Produce high-fidelity visual mockups from the wireframes.", "requirements": ["applies the design-system tokens", "specifies every visual state"], "resolved_id": null, "match_status": null },
      { "id": "reviewing-hi-fi", "version": null, "source": null, "category": "reviewing", "purpose": "Gate-check hi-fi mockups for build readiness.", "requirements": ["checks design-system fidelity", "verifies state completeness"], "resolved_id": null, "match_status": null },
      { "id": "deep-research", "version": null, "source": null, "category": "research", "purpose": "Ground project decisions in multi-source, cited research.", "requirements": ["gathers and cites multiple sources", "persists the evidence trail"], "resolved_id": null, "match_status": null },
      { "id": "external-content-sanitizer", "version": null, "source": null, "category": "utility", "purpose": "Neutralize prompt-injection in external content before use.", "requirements": ["detects injection attempts", "strips unsafe directives"], "resolved_id": null, "match_status": null }
    ],
    "tools": [
      { "id": "file-read", "name": "File Read", "type": "file-read", "access": "read-only", "credential_key": null, "auth_type": null },
      { "id": "file-write", "name": "File Write", "type": "file-write", "access": "read-write", "credential_key": null, "auth_type": null },
      { "id": "web-search", "name": "Web Search", "type": "web-search", "access": "read-only", "credential_key": null, "auth_type": null },
      { "id": "browser", "name": "Browser", "type": "browser", "access": "read-only", "credential_key": null, "auth_type": null }
    ],
    "capabilities": [
      {
        "id": "docs",
        "name": "Document Storage",
        "description": "Stores and retrieves text documents produced by the pipeline.",
        "required": true,
        "available_providers": [
          { "id": "local-docs", "name": "Local Docs Backend", "tier": "open-source", "supported": true },
          { "id": "github-docs", "name": "GitHub (docs folder)", "tier": "free", "supported": true },
          { "id": "confluence", "name": "Confluence", "tier": "paid", "supported": false },
          { "id": "notion", "name": "Notion", "tier": "paid", "supported": false }
        ],
        "selected_provider": null,
        "account": null,
        "status": "unassigned"
      },
      {
        "id": "design",
        "name": "Design Tool",
        "description": "Produces and hosts wireframes, hi-fi mockups, and design systems.",
        "required": true,
        "available_providers": [
          { "id": "penpot", "name": "Penpot", "tier": "open-source", "supported": true },
          { "id": "figma", "name": "Figma", "tier": "paid", "supported": false }
        ],
        "selected_provider": null,
        "account": null,
        "status": "unassigned"
      }
    ],
    "amendments": []
  }
}

与 v2.0.0 相比的重大变更：manifest.providers 重命名为 manifest.capabilities（已填充，而非 []）；文档条目使用标量 capability（而非 capabilities 数组）；manifest.roles、manifest.skills、manifest.tools 根据文档集填充；新增 manifest.amendments: []；添加 version/generated_at/schema 标头。

相关内容

• 内容/模板技能（例如 content-template-gateway）——撰写时的对应技能。与此技能配合使用：此技能选择文档集，该技能为每份文档提供模板。
• 调研技能（例如 deep-research）——用于调研不熟悉的文档类型（第 7 步）。
• reviewing-document-discovery ——专用审核工具，用于对照检查此技能的输出（自检项目 1–14 与审核条件 1–14 一一对应，且以同一来源为准）。
• references/document-type-catalog.md ——文档类型全集、各原型的比例表和典型依赖关系。在阶段 B 第 4 步加载。
• references/reference-architectures.md ——4 信号算法、参考架构表、规模测试和接口契约填写指南。在阶段 A 第 2 步加载。

渐进式披露

• references/classification-schema.md — 10 个 v2 分类簇（基于依据的字段 + 枚举令牌）以及 10 个 prior_art_triggers 公式。在阶段 A 第 1 步加载（分类 + 编写触发条件）。
• references/reference-architectures.md — 4 信号能力识别算法、10 个领域的参考架构表、三项规模测试、接口契约填写指南。在阶段 A 第 2 步加载（识别能力领域）。
• references/document-type-catalog.md — 七个层级 + 四个叠加项的目录（每种类型的名称 + 何时需要 + 提供内容）、按架构类型划分的承重/跳过表，以及常见的 depends_on 边。在阶段 B 第 4 步加载（选择文档集 / 领域叠加项）。
• references/manifest-schema.md — 第 8 步的自包含参考资料：docs/design 的提供方目录、角色定义、文档类型到技能的映射、文档到工具的映射。在阶段 B 第 8 步加载（填充元信息部分）。
• references/sources.md — 目录以及比例原则/依赖关系指南的研究来源。仅在审查指南的出处时加载。
• schemas/capability-map.schema.json — 用于验证 capability-map.yaml 的 JSON Schema 2020-12。IDE YAML 验证参考；运行时验证在 hq-core 的 Python 端进行。
• schemas/manifest.schema.json — 用于验证 manifest.yaml（documents[] + 五个元信息部分）的 JSON Schema 2020-12。与 references/manifest-schema.md 和 §Output contract 共用单一来源。IDE YAML 验证 + 确定性 discovery-qa 门禁；语义检查（唯一性、引用完整性、无环性、跨文件作用域）通过算法执行。
• scripts/validate.py — 确定性门禁：python scripts/validate.py <capability-map.yaml> <manifest.yaml> 会对两个文件进行 JSON Schema 验证，并执行算法检查（唯一性、文件内及跨文件引用完整性、depends_on 无环性、角色引用完整性 + 架构类型→配对一致性、先前成果触发公式、ISO-8601 generated_at、保留枚举的空白规范化）。退出码 0 = 通过；退出码 1 + 每项违规对应一行 FAIL <rule>: …。只读（绝不重写文件）。需要 pyyaml + jsonschema。生成两个文件后运行此脚本，并修复所有报告的问题，再将发现工作视为完成。参见 scripts/validate.py.validation.md。

正文预算

• description ≤ 1,024 个字符（以“Use when …”开头）。
• 正文软上限：约 1,000 行 / 约 10K 个令牌。目标是全面覆盖，达到生产级质量；这是软上限，不是硬限制。

更新日志

• 6.0.0（2026-07-10）— 破坏性变更（技能意图 + 解析字段）。每个 manifest.skills 条目新增必需的 purpose（该技能必须为此项目完成的工作）和必需的非空 requirements 列表（离散能力），并为每个技能填写；两者都会传入下游仪表板审批关卡，用于显示和严格匹配。每个技能和角色条目都新增由后端写入的 resolved_id（string|null）+ match_status（complete|partial|none|null），发现阶段输出为 null，由关卡写入。scripts/validate.py 新增解析一致性检查（match_status 为 complete/partial ⇒ 设置 resolved_id；为 none/null ⇒ resolved_id 为 null）。输出的 manifest.version → 3。schemas/manifest.schema.json：Skill 现在要求 purpose/requirements/resolved_id/match_status；Role 要求 resolved_id/match_status。更新了 references/manifest-schema.md 的第 1/4 节 + 步骤 8 + 自检项 13；同步更新了 reviewing-document-discovery 的条件 13（其版本为 1.5.0）。破坏性变更：v5 清单（技能没有 purpose/requirements）将无法通过验证。
• 5.0.0（2026-07-09）— 破坏性变更（清单审查角色）。新增清单缺少的审查维度。现在，manifest.roles 会根据存在的原型派生作者/审查者配对——document-author + document-reviewer（工程师/策略师）、designer + design-reviewer（设计师）——角色条目变为纯人物设定（移除 skills/tools；这些是任务执行机制，调度时根据文档条目 + 顶层章节解析）。每个文档条目都将单一的 role 字段替换为 roles: [author, reviewer]（恰好两个，顺序固定），并在其 skills 中包含作者和审查者的技能。scripts/validate.py 新增角色引用完整性检查（每个 document.roles ID 都能解析到一个 manifest.roles 条目）和原型→配对一致性检查（重新计算固定映射）。输出的 manifest.version → 2。schemas/manifest.schema.json：Role 移除 skills/tools；Document 的 role → roles（minItems/maxItems 均为 2）。更新了 references/manifest-schema.md 的第 1/3/4 节 + 步骤 8 + 自检项 3/13；同步更新了 reviewing-document-discovery 的条件 3/13（其版本为 1.4.0）。破坏性变更：v4 清单（单一 role 字段，角色包含 skills/tools）将无法通过验证。
• 4.0.0（2026-06-26）— 破坏性变更（capability-map v2）。capability_map 采用完整的v2 分类体系：10 个有依据的聚类（删除 team；新增 business + integrations；扩充 archetype/domain/regulatory/scale/security/ui/data_ml/infrastructure），并使用以研究为依据的枚举令牌集（ASVS、WCAG、EU AI Act、九个 9 的等级体系、数据分类、EIP 模式、计算范式，等等）。现在，prior_art_triggers 由模型编写（发现者应用 references/classification-schema.md 中的 10 条公式），不再省略；并由验证器保证：scripts/validate.py 会重新计算每条公式，若不匹配则失败。架构现在是严格的（各聚类设为 additionalProperties:false；[trigger] 输入字段为必需项）。重写 Phase A 步骤 1 + 新增 references/classification-schema.md。reviewing-document-discovery 的条件 10 改为以 v2 聚类为唯一来源（其版本为 1.3.0）。发布运行手册关卡重新对齐 v2 原型令牌 {cli-tool, library-sdk}。依据生产级手册（P0 种子 → P1 角度 → P2 档案）建立分类。product_capabilities + 文档扇出保持不变。破坏性变更：v1 capability_map 将无法通过验证。
• 3.3.0（2026-06-25）— 增量更新。改进文档扇出的比例性和完整性（首次通过发现冒烟测试后发现的四项选择修正）。新增按能力扇出的行（步骤 5）：technical-design-{id} 由新的可选 impl_complexity ∈ {moderate, complex} 控制；model-card-{id} 由新的可选 has_model 控制；user-flows-{id} 由 has_ui 控制。新增按规则选择的系统文档（步骤 4）：user-flows（任意 has_ui）、release-runbook（原型不是 library/CLI）、eval-plan（任意 has_model）。从六条目录 depends_on 边中移除虚构的 nfrs-security ID——NFR 已并入 prd/feature-spec/architecture-doc/threat-model，不是独立文档。model-card/eval-plan 从 data/ML 叠加层移至规则选择。架构 + 接缝契约 + reference-architectures 指南中新增两个可选 CapabilityRecord 字段（impl_complexity、has_model）；新增 test_validate.py 黄金样例用例，覆盖每种新文档类型。model-card/eval-plan 的技能映射行设为 forge-on-gap（技能尚未构建）。自检不变（保持与 reviewing-document-discovery 中的对应内容同步）。向后兼容：此前所有有效的 capability-map/清单仍然有效。
• 3.2.0（2026-06-25）— 增量更新。放宽架构约束 + 确定性验证器。两个架构都移除硬性 maxLength 上限，改为描述中的软性指导；将随现实变化的枚举开放为自由文本 + 推荐词汇表（compliance_requirements、cloud_provider、auth_type、skill.category、tool.type）；扩展 ui_types，但仍保持封闭（+voice/wearable/ar-vr/tv）；owns 的 minItems 从 1 改为 0。有限的概念分类体系（包括 expected_users）仍为硬性枚举；ID 模式 + 结构仍为硬性要求。新增 scripts/validate.py（+ .validation.md、test_validate.py）：确定性关卡——对两个文件执行 JSON Schema 验证，并检查唯一性、文件内/文件间引用完整性、depends_on 无环性、ISO-8601，以及保留枚举的空白字符规范化。SKILL.md 新增保留枚举原样输出的指南、开放字段的推荐词汇表，以及软性限值说明。向后兼容：此前所有有效文档仍然有效。
• 3.1.0（2026-06-25）— 增量更新。新增 schemas/manifest.schema.json（JSON Schema 2020-12），与 capability-map.schema.json 保持一致，并与 references/manifest-schema.md + §Output contract 同一来源——包含 documents[] 和五个元数据部分。为 manifest.yaml 提供 IDE YAML 验证，以及供确定性 discovery-qa 关卡使用的机器可验证契约。方法/输出没有变化。
• 3.0.0（2026-06-21）— 破坏性变更。Phase B 新增步骤 8：使用 references/manifest-schema.md，根据已整理的文档集填充清单全部五个元数据部分（capabilities:、roles:、skills:、tools:、amendments: []）。文档条目：capabilities: [...]（数组）→ capability: "..."（字符串标量）。清单输出：providers: 键重命名为 capabilities:（has_ui: true 时填入 docs + design；不包含构建级能力）。明确规定输出契约：技能返回一个包含三个键的 JSON 对象，不写入文件，由调用方将 capability-map.yaml + manifest.yaml 写入 scope_root。自检新增第 12 项（清单输出结构）、第 13 项（填充元数据部分）和第 14 项（capability 标量）。新增参考文件：references/manifest-schema.md。
• 2.0.0（2026-06-21）— 破坏性重构。内部工作流分为两阶段：Phase A（跨 10 个维度对项目分类 + 使用四信号算法识别产品能力领域）；Phase B（扇出清单——按能力创建文档条目，并包含范围 + 能力字段）。输出契约改为三键 JSON {capability_map, product_capabilities, manifest}，其中 manifest 改为嵌套结构（原为根级）。新增扇出规则：始终包含 feature-spec；根据标志包含 data-model/api-spec/wireframes/hi-fi；wireframes+hi-fi 使用 design 能力。更新修改方法：同时接收 capability-map.yaml 和 manifest.yaml；采用双提示词流程（提示词 A 分类 T1–T5 → 关卡检查 T4/T5 → 提示词 B 生成记录）；明确规定仅增补不删除的约束。自检新增第 10 项（4–10 个 L1 领域、规模测试）和第 11 项（按能力扇出的条目与标志匹配）。新增参考文件 references/reference-architectures.md，于 Phase A 步骤 2 加载。新增架构文件 schemas/capability-map.schema.json。正文软性预算上调至约 1,000 行 / 约 10K 个令牌。
• 1.3.0（2026-06-15）— 生产级重新设计（增量更新）。明确自检（九项完成定义）。新增迭代/修改方法。命名的比例性方法（ISO 15289 裁剪 + ROI）。重新以 ISO/IEC/IEEE 15289 + 12207 为依据。
• 1.2.0 / 1.1.0 — 扩展目录（Band 0 + Band 6 + 四个领域叠加层；生命周期带从 5 个增至 7 个）。
• 1.0.0（2026-06-03）— 初始审核版本。