propose

技能：提案

WHAT

目的和背景

• 目的： 在编写代码前规划功能或变更。明确对现有功能的影响，并在实施前达成一致。
• 触发条件（何时使用）：
  • 用户请求新增功能、端点、组件或行为
  • 变更涉及共享代码或核心代码
  • 范围不明确或存在多种解释
• 非目标： 不编写代码（在审批关卡处 STOP）；不生成代码级实施计划（那是 /plan 的工作，在 SPEC 获批后运行）；除非用户要求，否则不采访用户（/br interview）。

心智模型

请求 → 强制查询 wiki（背景信息）→ 未知项 → 影响 + 副作用 → 方案（2–3 个，说明选择理由）→ SPEC 草案 .md（FR/SC id、假设（默认）/[需要澄清]）+ 配套 .html（每个任务都有 archify 图示 + 说明）→ 自我审查 → 在审批关卡 STOP → /plan。

此技能的产出——以及有意不做的事

/propose 生成 SPEC（设计文档）：供人在审批关卡阅读并点击批准。它不是实施计划。 代码级计划（准确路径、函数签名、测试、逐步编写代码）由技能 /plan 负责，在 SPEC 获批后运行。

拆分的原因（对照 obra/superpowers，spec:plan 比例约为 1:8——82–511 行对比 673–2621 行）：如果把代码级内容塞进 SPEC，草案就会膨胀到让审批者无法读完自己正在批准的内容，审批关卡也会失去作用。两份文档，两类读者。

输入和输出约定

	字段	是否必需？	含义
输入	功能/变更请求	是	在步骤 1 用一句话重述
输入	wiki（concepts/、entities/、sources/adr/、decisions.md）	是	起草前强制查询
输出	llmwiki/wiki/sources/draft/DDMMYY-feature-name-module.md	是	frontmatter 中包含 type: draft，并具备 R7 要求的全部章节（Context、Global constraints、Non-goals、Approaches、Plan、FR、SC、Assumptions、Agent Task Assignment、Sequence diagram、Self-review）
输出	llmwiki/html/DDMMYY-feature-name-seq.html + 每个任务的 spec/artifact archify 图示	是	每个任务都包含 engine 图示 + 完整说明，并提供双向链接
输出	llmwiki/wiki/index.md + llmwiki/wiki/log.md 中的条目	是
输出	task id T-YYMMDD-NN	否（失败时放行）	frontmatter 中的 task:
输出	草案交付报告	是（无 artifact 时除外）	Delivery 章节

规则和能力

• RULE-01（MUST）：OKF v0.1（R9）： 草案以 YAML frontmatter 块（---）开头，其中包含 type: draft（可选包含 title/status/tags/timestamp/task）；复制 sources/draft/_template.md。在正文中保留 **Status:** proposed，以便 R7 进行审核。
• RULE-02（MUST）：不得在此技能执行期间开始实施。
• RULE-03（MUST）：提案必须成对提交：.md + .html（每个任务一张图）。Validator R7 会在写入和提交时阻止不完整的提案——在申请审批前修复。
• RULE-04（MUST）：如果影响列表为空，明确写明“No existing code affected.”
• RULE-05（MUST）：如果有多种方案，列出并说明权衡——不得默默选定方案。
• 能力：读取 wiki 和 repo（查证事实）；在 wiki 中写入草案、HTML 页面和 spec 图示；通过绘图引擎渲染图示；记录未知项和 task id（失败时放行）；不写入产品代码。

失败边界

• SPEC 中仍有未回答的 [需要澄清] → 在审批关卡被阻止（R7-n）。
• 草案缺少 R7 要求的章节（Context/Global constraints/占位符……）→ validator 会在写入和提交时阻止；申请审批前先修复。
• 经过 2 轮 spec 修改后，图示渲染仍显示红色 → 停止并询问用户，不要重复验证。
• code-logger.py --task 出错或缺失 → 输出“跳过”，留空 task:，不阻止流程（失败时放行）。
• 用户尚未批准 → 在步骤 9 停止；没有 PLAN 时不要 dispatch。

HOW

主工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	确定性	wiki	步骤 0：强制查询 wiki → ## Context	上下文 + 引用	—
W02	判断	请求	步骤 0b：查找未知项；区分事实（查询）/决策（(default) · 以后再查 · [CẦN LÀM RÕ]）	分层后的未知项列表	架构层失败 → [CẦN LÀM RÕ]
W03	判断	请求、repo	步骤 1–5：重述、影响、副作用、最简计划、成功标准	SPEC 内容	影响为空 → 写入“No existing code affected.”
W04	执行	W01–W03	步骤 6：撰写包含所有 R7 条目的 .md 草稿 + task id + 索引/日志	磁盘上的草稿	R7 阻止 → 修改
W05	执行	计划	步骤 7：配套 HTML — 为每个 task 将 spec archify，渲染一个 shell 命令，嵌入 iframe + 正文，shell docs-site-macos	.html + artifact	两轮后仍报错 → 停止并询问
W06	判断	草稿	步骤 8：用 3 个检查点进行自审，并就地修改	## Self-review	—
W07	执行	草稿 + html	步骤 9：停止，展示草稿 + HTML URL，等待批准	批准 / 转向	未批准 → cancelled/redirect
W08	执行	已批准的 SPEC	步骤 10：移交给 /plan	PLAN	—

各步骤的详细信息（W01–W08 的事实来源）： 0. 起草前必须先查询 wiki——查询／阅读 wiki（concepts/、entities/、sources/adr/、decisions.md），查找相关概念／ADR／决策；将摘要写入草稿的 ## Context，并引用 [[wikilink]]／路径。禁止“盲目”提案（R7-f 会阻止缺少有内容的 ## Context 的草稿）。 0b. 起草前找出未知项（地图 ≠ 领土，GH#40——参见 fdk/wiki/concepts/map-not-territory.md）：模型越强，越会用自信的答案填补模糊之处。写 SPEC 的第一行之前，简要列出“要正确完成这件事，我还不知道什么？”——检查地图最容易撒谎的 5 个方面：(a) 请求者未明说的意图，(b) wiki 或 CLAUDE.md 中没有记载的团队惯例，(c) 真实的数据形态（schema、sample、边界），(d) 运行环境（version、env、权限），(e) wiki 编写后发生的变化。每个未知项都应归入下方 ## Assumptions 的相应层级：事实 → 查证；低风险决策 → (default)；需要之后复核 → (default, find-out-later → unknown-ledger)；如果判断错误会导致架构损坏 → [需要澄清]。没有未知项，说明的是还没查找，不是已经理解。

1. 用一句话重述请求，以确认理解。
2. 列出所有受影响或必须修改的现有文件、函数或模块。
3. 列出所有可能因此受到影响而出问题的现有功能或行为。
4. 用编号步骤提出最小化实施计划。
5. 说明成功的可验证标准。
6. 在 llmwiki/wiki/sources/draft/DDMMYY-feature-name-module.md 创建草稿文件（例如 260425-new-approval-button-fe.md），其中包含步骤 1–5 的提案内容。草稿必须包含以下内容（由验证器 R7 强制执行——缺少时会在写入和提交时阻止）：
   • ## Context——摘要步骤 0 查询到的相关 wiki 内容（概念／ADR／决策），并引用 [[wikilink]]／路径（强制基于查询结果——若缺失／为空，R7-f 会阻止）
   • ## Global constraints——适用于所有任务的约束，从 wiki／ADR／policy 中逐字照录实际值（最低 version、dependency 限制、命名规则、push 前的必经 gate 等）。每项任务都隐含包含此 section；执行 Agent 只能看到自己的任务，因此所有人都需要遵守的通用约束必须集中放在一个人人都能获取的位置。缺失／为空时，R7-h 会阻止。
   • ## Non-goals——明确哪些内容不做。没有此项，执行过程中 scope 会不断扩散。
   • ## Approaches——提供 2–3 个本质上不同的方案，说明每种方案的权衡，并指出所选方案及选择原因。禁止暗中选择。
   • ## Plan——将任务列为 - [ ] 检查清单项
   • ## Requirements (FR)——为每项功能要求设置稳定 ID：**FR-001**: 系统必须……。这是 PLAN 进行反向追溯的锚点（R18 会阻止 PLAN 遗漏任何 ID）。
   • ## Success criteria (SC)——为每项成功标准设置稳定 ID：**SC-001**: …。参见下方“标准必须衡量人，而不是机器”一节。
   • ## Assumptions——列出所有用户未说明、由模型自行补全的字段，每行都标记 (default)。参见下方“自行补全还是提问”一节。

事实还是决策 — 先查，再问，自行补全中间部分

在“自行补全还是提问”之前，还有一个问题：这是事实（FACT）还是决策（DECISION）？

• 事实 — 有一个正确答案，可以通过探索环境查到：读取文件、运行命令、grep、查看 git remote -v、读取 package.json。→ 去查，绝对不要问。 问用户一个工具能回答的问题，是在浪费他们的轮次，也会让他们觉得你不会读取环境。
• 决策 — 没有正确答案，而是一种选择。接下来才需要根据下面的规则，区分 (default) / [CẦN LÀM RÕ]。决策由用户做出——但大多数低风险决策都应自行填入合理默认值并明确说明，只有高风险时才升级为提问。

界限：如果你可以通过一条命令查出来，那就是事实——去查。如果两个理性的人可能做出不同选择，那就是决策——按下面的层级处理。

用户未说明的设计选择 = 低风险决策 → 从基础中补全，不要提问。 如果需求涉及 UI，但用户没有明确说明宏观结构、主题、字体搭配或锚点颜色，不要采访用户——从目录 [[design-foundation]] 中选择符合需求的默认值（来源：skills/hallmark/references/macrostructures/ + references/genres/），标记为 (default)，并将所选的宏观结构和主题名称写入 ## Assumptions。用户扫一眼就知道机器选了什么，不喜欢的话改一行即可。宏观结构选错了，很快就能改——这又不是身份验证或钱。这是补全未知设计项的参考来源，纳入正确的 (default) 体系中。（带有创作意图的需求若没有合适的主题 → hallmark 自动转到 Custom 分支；仍然执行 6 discipline + slop-test。）

自行补全还是提问 — 默认是自行补全

用户已经描述了所有他们知道的内容。不要询问他们不知道的事——自行补入合理的默认值，然后明确说明是你补的：

• (default) — 模型自行选择。继续执行，不要提问。审核者扫一眼 ## Assumptions，就能分辨哪些是用户的说法，哪些是机器的说法，并修改自己不同意的那一行。

• (default, find-out-later → [[unknown-<slug>]] U-NN) — 中间层级：模型现在就填入一个默认值，避免阻塞工作，但要将其记为有记录的欠项，而不是默默处理。适用于默认值有风险，而且我们知道之后必须复核的情况——包括将 [CẦN LÀM RÕ] 降级的情况（用户说“先填上，以后再说”）。使用 python3 harness/scripts/unknown-ledger.py --add … 记录欠项 → 它会输出 U-NN，将其贴到 Assumptions 行中。这笔欠项不会阻塞关卡——只会显示在 /lint 中，避免被埋没。参见 [[150726-unknown-ledger]]。

• [CẦN LÀM RÕ: <câu hỏi cụ thể>] — 模型拒绝猜测，直接放在 SPEC 中对应的位置。仅用于默认值一旦出错就会破坏架构或伤害用户，且符合 CLAUDE.md 中例外条件的类别：

  • 身份验证 / 权限管理机制（谁可以做什么）
  • 数据存储：存什么、存在哪里、保存多久、谁可以读取
  • 钱 / 支付 / 限额
  • 具有法律或合规后果的事项
  • 任何信任边界（外部输入、系统边界）

  如果 SPEC 中仍有尚未回答的 [CẦN LÀM RÕ]，R7-n 会阻止审核关卡。 用户回答后 → 替换为实际值；用户说“你就猜吧” → 有意地降级为 (default)，并留下记录。

颜色按钮选错，三十秒就能改。身份验证机制选错，那个 (default) 就会悄无声息地变成一项架构决策，而审核者会略过，因为它看起来已经处理完了。单独使用 (default)，就是让猜测看起来名正言顺的机器；只有和 [CẦN LÀM RÕ] 搭配时，它才安全。

只有用户提出要求时才运行采访（/br interview）——运行时最多 5 个问题，按（影响 × 不确定性）选择。

选择题形式的采访始终要有一个最后选项：“现在填入默认值，之后再了解（记录 unknown 欠项）”。 用户不确定、不想停下来思考，但也不想让模型暗自猜测 → 选择此项：模型立即填入合理的默认值（让工作继续进行），并在记录簿中登记一个 unknown，以便之后补上。这是用户尚未准备好回答时的通用退路，同时仍保留可追溯性——不强迫用户回答，也不默默猜测。

偿还 unknown——获得真实信息时

已记录的 unknown（(default, find-out-later)）不是让你忘记的。获得真实信息后：

1. 在源 SPEC/PLAN 中填入正确值——将 (default, find-out-later → …) 替换为真实值。
2. 结清记录： python3 harness/scripts/unknown-ledger.py --resolve --file unknown-<nguồn>.md --id U-NN --value "<giá trị đúng>" --fixed "<sửa ở đâu>" --date <YYYY-MM-DD>。记录簿会保留已填入的值和正确值（用于审计——六个月后可以知道模型当时猜了什么、猜得对不对，以及在哪里修正）。
3. 如果错误的默认值已经导致代码出错（已基于猜测值执行）→ 打开 /orca-issue（先复现）或 /raise-issue，并在正文中反向链接 U-NN。

未结清的记录会显示在 /lint 中（报告，不阻断）——unknown-ledger.py --list。偿还是由人员/Agent 有意采取的行动；技能只提供流程，不会自行“调查”并代劳。

需要提问时——用正确的方式提问：

• 每轮只问一个问题。 等待回答后再问下一个。一次问一堆会让人困惑，也容易得到敷衍的回答。
• 始终附上推荐方案，并放在最前面，这样用户只需点头（“同意”/“第一个”）即可，无须自己组织答案。

衡量标准必须衡量人，而不是机器

SC-xxx 必须可衡量且不依赖技术——说明用户能获得什么，而不是机器做了什么：

• ✅ “用户在 2 分钟内完成账户创建” · “支持 1000 人同时使用且性能不下降” · “将有关 X 的支持工单减少 50%”
• ❌ “运行 pytest 得到 exit 0” · “validator 返回 2”——这衡量的是机器。系统即使所有检查都通过，也仍可能毫无用处。 机器层面的检查仍然记录，但记录为 SC-xxx 的证据，而不是替代它。
  • ## Agent Task Assignment — 表格 | Task | Agent (CLI) | Lý do chọn | Status |，每个任务一行，Agent 单元格不得为空，Status=pending。根据成本表选择 Agent；如果全部使用同一个 Agent，说明原因。
  • **Sequence diagram:** 链接到配套的 .html（磁盘上必须存在）
  • 持久 Task ID（支柱 3 — 尽力而为、失败时放行）： python3 harness/scripts/code-logger.py --task new title="<feature>" → 输出 T-YYMMDD-NN；写入 frontmatter：task: T-YYMMDD-NN。命令失败时放行——旧版安装缺少 --task 或 store 出错时 → 输出“跳过”，将 task: 留空，不得阻止 propose。这是 gate/dispatch/verify 用于推进生命周期并锚定到不可变审计轨迹（chained 的 events.jsonl）的 ID。 在 llmwiki/wiki/index.md 中添加一行，并追加到 llmwiki/wiki/log.md。

7. 在 llmwiki/html/DDMMYY-feature-name-seq.html 创建配套 HTML 页面。对于 Plan 中的每个任务，页面都必须包含以下两个部分——真实图表和丰富的文字说明。只有文字说明，或只有伪装成图表的步骤列表，都是不完整的（R7-c，来自 100926：只计算页面嵌入的 archify 成品，每个任务一个）：
   • (A) 每个任务的 Sequence diagram — 由引擎绘制，绝不手工制作。 每个任务编写一个 archify sequence 规格（llmwiki/html/DDMMYY-feature-name-tN.sequence.json；参与者 = lifelines；消息变体：indigo = 现有，emerald = 新增/更改，amber = 阻止/失败），并通过 /diagram → archify 渲染。在一次 shell 调用中批量处理所有任务，这样 N 个图表只需一次模型轮次：for s in llmwiki/html/DDMMYY-feature-name-t*.sequence.json; do o="${s%.sequence.json}.html"; node ~/.agents/skills/archify/bin/archify.mjs deliver sequence "$s" "$o" --json && node ~/.agents/skills/archify/bin/archify.mjs visual-check "$o" --json; done。**规格修复最多 2 轮：**第二轮后仍然为红色 → 停止并询问用户，绝不要在 validate 上循环（实测 100926：单个页面进行了 57 次 validate 轮次，约 430k 上下文 ≈ 44M 缓存读取 tokens）。不要设置 meta.visual_preset（安装默认值 macos 与页面外壳匹配）——绝不要从 archify/examples/*.json 复制 signal-flow；只有用户要求时才设置其他 preset，并在页面上声明 <meta name="overstack-preset" content="<preset>">（否则 R20 会阻止主题不匹配的嵌入）。使用 docs-site-macos §嵌入外部成品 recipe 嵌入每个成品——<iframe class="archify-embed" src="DDMMYY-feature-name-tN.html"> + 自动高度脚本 + “单独打开图表 ↗”链接（固定高度的框架总会裁切内容：查看器高度为 905–1565px）——标题标明任务，并加上注明所分配 Agent 的徽章。旧版列表模板（diagram-box + .lifeline 芯片 + .msg 行）不是 Sequence diagram，不再计入。
   • (B) 丰富的详细说明——与每张图表并列，提供易读的完整句子说明（而不是简短的图表标签）：变更内容及原因、运行时的数据/流程、安全分支与阻止分支，以及具体风险。这是供人阅读的文档 → 遵循文字说明规则（CLAUDE.md 2026-06-27）：此处绝不要使用简略或过度压缩的表达。图表是骨架；文字说明是躯体——两者缺一不可。
   • 风格： 使用 Skill 工具加载 /docs-site-macos 并遵循其要求，构建页面外壳（页眉、文字卡片、徽章）——液态玻璃风格（浅色渐变背景 + 折射图层 + 二级玻璃卡片 + Apple 色调徽章）以及其 §Navigation 侧边栏（每个章节/任务一个链接、.nav-toggle/.nav-close、滚动定位、主题切换）。未加载技能、仅模仿风格，曾导致一个有 11 个章节却没有菜单的页面（GH#155）；R20 现在会阻止有 3 个以上章节且没有 <nav> 的 */html/*.html 页面。绝不要手工制作暗色/扁平主题（教训 250626 “怎么这么难看”）。不要克隆旧版 *-seq.html 的图表部分——那些是步骤列表，不是图表（教训 100926）。
   • 编写分工——Claude 思考，成本较低的 CLI 渲染： .md 是实质内容（Claude 的工作），必须完整到可渲染——除了 Plan + 文字说明，还要包含 ## Render brief 章节，为每个任务列出图表的有序步骤（每步标记为 legacy / add / block）以及完整的文字说明段落。随后 .html 是该 brief 的机械式渲染结果；在编排运行中，可以交由成本较低的 CLI（OpenCode big-pickle / agy / kiro，$0）处理——参见 orca-workflow。独立运行 /propose 时：由 Claude 直接渲染，## Render brief 可选。由于委派渲染是免费的，.html 应优先采用完整的 docs-site-macos 丰富度，而不是精简页面——Claude 的 token 成本只用于实质内容，不会随 HTML 丰富度增加。
   • 双向链接：.md ↔ .html
8. 自我审查——以全新视角重新检查，并就地修正。 将结果记录到草稿的 ## Self-review 中（3 项检查）：
   1. 需求覆盖 — request 中的每项需求都只能归属到一个 task。若有遗漏 → 添加 task。
   2. 扫描占位符 — 不得残留 TBD、TODO、“适当处理错误”、“handle edge cases”、“与 Task N 类似”。R7-g 会拦截。
   3. 名称与类型一致性 — 同一事物在整份草稿中必须使用相同名称（task 3 中的函数 clearLayers() 到 task 7 却变成 clearFullLayers()，就是写作过程中产生的 bug）。 找到问题就直接修正，无需进行第二轮审查。
9. 停止。不要编写代码。展示草稿内容 + HTML 预览 URL。等待用户批准或指示调整。
10. 用户批准后——移交给 /plan（Skill 工具 → plan），将此 SPEC 扩展为可执行的 DDMMYY-<tên>-PLAN.md。没有 PLAN 时不要 dispatch task：以 headless 模式运行的低成本 CLI Agent 不会继承任何上下文，也无法追问——它只有我们注入的内容（教训 250626：brief 单薄时，交付量约为 1/5）。

分支

ID	类型	条件	行为	跳过 / 失败	汇合
B01	user_optional	用户要求进行访谈（/br interview）	提出最多 5 个问题（影响 × 不确定性），每轮一个问题，并附上建议和“现在填入默认值，之后再了解”的答案	未要求 → 自动填入 (default)	W03
B02	conditional_required	默认值有风险，且已知之后需要重新检查	(default, find-out-later → …) + unknown-ledger.py --add 获取 U-NN	—	W03
B03	recovery	已有关于某个已记录 unknown 的真实信息	将正确值填入 SPEC/PLAN + unknown-ledger.py --resolve …；错误默认值已产生代码 → /orca-issue 或 /raise-issue	—	主流程之外
B04	capability_optional	在编排流程中运行	可将 ## Render brief 渲染为 .html 的任务交给成本较低的 CLI（参见 orca-workflow）	单独运行 → Claude 直接渲染	W06
B05	conditional_required	brief 涉及 UI，且用户未说明宏观结构 / 主题	从 [[design-foundation]] 填入，并在 ## Assumptions 中记录宏观结构名称 + 主题	—	W03

验证与停止

Validator R7（分支 R7-c/f/g/h/n）、R18、R20 会在写入和提交时确定性拦截；三重视角自审属于审查环节。规格说明图的修改循环上限为 2 次。Skill 始终在 W07 停止——没有任何通往代码的路径。

示例

• 正向：“在审批页面添加快速审批按钮” → 查询 wiki 获取相关 ADR，Assumptions 中将按钮颜色记为 (default)，起草 260425-new-approval-button-fe.md + 260425-new-approval-button-seq.html，每项任务附带 archify 图表 → 自审通过 → 停止，展示草稿 + URL，等待审批。
• **边界 / 失败：**请求“让客户查看付款历史”，但未明确哪些人可以读取数据 → SPEC 中写入 [CẦN LÀM RÕ: role nào được xem lịch sử thanh toán của người khác?] → R7-n 阻止审批，直到用户回答。

交付 — 输出报告

所有主要 skill 任务完成后，向 wiki 写入一份提案草稿。

步骤

1. 构建文件名：

• 格式：DDMMYY-<ten>.md
• DDMMYY = 今天的日期（例如，2026 年 6 月 2 日为 020626）
• <ten> = 用 2–4 个 kebab-case 单词概括所做的工作（例如，landing-page-coteccons、brand-kit-fintech、ingest-auth-spec）

2. 写入 llmwiki/wiki/sources/draft/DDMMYY-<ten>.md：

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

# DDMMYY-<ten>
**Type:** draft
**Status:** proposed
**Tags:** <skill-name>, output-report
**Proposed:** YYYY-MM-DD

## What
<One sentence — what this skill invocation produced or decided>

## Output
<Key artefacts, files created/modified, or decisions made>

## Files
| File | Action |
|------|--------|
| `path/to/file` | created / modified |

## Notes
- Invoked via: `/<skill-name>` skill

## Origin
- **Draft:** `wiki/sources/draft/DDMMYY-<ten>.md`
- **Commit:** _(filled by verify-before-commit)_
- **Date promoted:** _(filled by verify-before-commit)_

3. 更新 wiki 索引和日志：

• llmwiki/wiki/index.md — 追加一行：| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |
• llmwiki/wiki/log.md — 追加：## YYYY-MM-DD — <skill-name> — <ten>

仅当该 skill 未产生任何产物，也未产生任何决策时才跳过（例如，像 /caveman-stats 这样的纯展示模式）。