failure-flywheel

技能：failure-flywheel

将反复出现的失败转化为规则。通过代码记录，以确定性方式计数，起草供人工审批的存根——绝不自动晋升。

内容

目的和背景

• 目的： 将 Agent 的重复失败转化为防护规则：通过代码记录失败，按分类体系进行确定性计数；当某类失败超过阈值时，生成规则/技能提案的 STUB，进入 propose→gate 流程。
• 触发条件（何时使用）：
  • 某项任务以可能再次发生的方式失败了（编造 API、破坏测试、忽略规则、过度构建）。记录下来，让它能够被计数，而不是被遗忘。
  • 定期（会话结束时，或每发生 N 次失败时）：使用 --report 查看哪类失败最常发生。
  • 某类失败达到重复阈值时：使用 --draft <category> 创建候选规则的种子，然后运行 /propose 完成后续流程。
  • 用户说“记录这次失败”“记录这个错误”“为什么总是发生这种情况”“将失败转化为规则”“失败分类体系”“哪些问题反复出现”，或使用 /failure-flywheel。
• 非目标： 不要用它自动编写规则。此技能只为审批流程准备种子；始终由人工审批。不要自行提炼规则内容（需要判断的 10% 交由人和 /propose 处理）。

心智模型

failure → record(category) → failures.jsonl → --report（分组 · 计数 · 排行榜）→ 类别 ≥ recurrence_threshold → --draft stub → /propose → 人工审批关卡。Hamel：创建 → 标记 → 修复 → 重复。机器完成 90% 的机械工作；“规则真正是什么”这 10% 由人来判断。

输入和输出约定

	字段	必填？	含义
输入	<category> + "<summary>"	是（record）	最接近的分类类别；未知类别仍会记录，并在报告中标记
输入	--detail "..."	否	补充详情
输入	--date YYYY-MM-DD	否（draft）	仅接受 ISO 格式，默认值为 2026-06-29；格式错误 → exit 2
输入	harness/failure-flywheel.config.yaml	是	阈值 + 分类体系（适配器，verified: false）
输出	failures.jsonl 中的一行	是（record）	本地历史记录，已加入 gitignore
输出	排行榜	是（report）	按类别计数，记录首次/最近出现时间，以及哪些类别为 DRAFT
输出	llmwiki/wiki/sources/draft/DDMMYY-failure-<category>.md	仅在达到阈值时	STUB（OKF frontmatter + ## Origin，不含 ## Plan）——等待人工处理

规则和功能

• RULE-01（必须）：记录采用 fail-open 机制——记录失败绝不能中断会话。
• RULE-02（必须）：绝不自动晋升。--draft 为 /propose 准备种子；由人工审批。
• RULE-03（必须）：草稿文件名中的日期固定（--date，默认值为 2026-06-29，仅接受 ISO 格式 YYYY-MM-DD——不是 wiki 文件名约定中的 DDMMYY），以确保确定性；实际使用时可以填入当天日期。现在，格式错误的 --date 会以 exit 2 退出并给出明确错误，而不会静默回退到默认值（此问题于 2026-07-20 修复；此前相同的静默回退导致生成了日期错误的草稿文件）。
• RULE-04（必须）：阈值或分类体系只能在配置中定义，不得硬编码在其他位置——配置就是适配器。
• 功能：在本地追加失败历史记录；读取阈值/分类体系配置；向 wiki draft 写入一个草稿存根文件。不访问网络，不修改实际规则/技能。

失败边界

• 记录失败 → fail-open（会话不中断），不阻塞。
• --draft 的类别未达到阈值 → 不写入存根（范围受限的 blocked，报告当前计数）。
• --date 格式错误 → failed，exit 2，并给出明确提示。
• 配置仍为 verified: false → 存根只包含供人工填写的 TODO，不自动编写规则（这是有意设计的 partial）。

使用

主要工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	effect	刚发生的失败	在最近的 taxonomy 层级下执行 record <category> "<summary>"	jsonl 行	未知 category → 仍然记录 + 在 report 中标记
W02	deterministic	failures.jsonl + config	--report 读取排行榜	达到阈值的层级标记为 DRAFT	没有层级达标 → 停止
W03	effect	达标的层级	--draft <category> 生成 stub	draft stub 文件	未达到阈值 / --date 错误 → 停止
W04	judgment	stub	停止并等待人工处理；由人工运行 /propose，将其变为带 gate 的 rule/skill	完整的 proposal	人工拒绝 → 保留 stub

各步骤详情（W01–W04 的真实依据）：

飞轮（Hamel：创建 -> 标记 -> 修复 -> 重复）

缓慢的人工步骤是“注意到同一个错误不断发生，并把它变成一条规则”。这样，机械部分的 90%（捕获 + taxonomy + 计数 + 脚手架）就能确定性地完成，同时拒绝假装那需要判断力的 10%（规则究竟是什么）也能自动完成。

命令

# 1. CAPTURE — append one failure (BY CODE; failures.jsonl is gitignored local history)
python3 harness/scripts/failure-flywheel.py record <category> "<summary>" [--detail "..."]

# 2. REPORT — deterministic taxonomy: group by category, COUNT, leaderboard (most-frequent
#    first) + first/last seen + which classes are eligible to draft
python3 harness/scripts/failure-flywheel.py --report

# 3. DRAFT — only if <category> recurs >= recurrence_threshold: scaffold a STUB proposal at
#    llmwiki/wiki/sources/draft/DDMMYY-failure-<category>.md and STOP for human approval
python3 harness/scripts/failure-flywheel.py --draft <category> [--date YYYY-MM-DD]

步骤

1. 发生失败时，在最接近的 taxonomy 类别下用 record 记录（参见 config）。捕获操作绝不会阻塞——未列出的类别仍会被记录，并在 --report 中标记。
2. 运行 --report 查看排行榜。标记为 DRAFT 的类别表示其重复次数 >= 阈值。
3. 对符合条件的类别，运行 --draft <category>。它会写入一个有效的 draft STUB（OKF frontmatter + ## Origin，刻意不包含 ## Plan，以便作为种子通过 R7 gate），其中包含模板化的“TODO: 从这 N 次失败中提炼规则”+ 失败列表。
4. stub 会在此停止，等待你处理。运行 /propose 将其变为完整且带 gate 的 rule/skill。FailureFlywheel 绝不会自动晋升——gate 始终由人工把关。

打包成供下次使用的指引（用户 23/09/2026）

当错误类别达到 recurrence_threshold（默认为 3——也就是超过 2 次）时，record() 会立即自动打包成一张指引卡片：

harness/metrics/guardrails/failure-<lớp>.md     # máy gói, có INDEX.md; được commit để phiên/máy khác cùng học
python3 harness/scripts/flywheel.py --kind failure --guardrails   # gói lại toàn bộ lớp đã đủ ngưỡng

卡片只从已记录的行中提炼信息（症状 + 已采用的修复方法 + 次数 + 最近一次发生时间）——不会编造新规则。session_start hook 会在每个会话开始时打印最新的 5 张卡片（位于 🧯 [已学习] 部分），因此下次遇到同类任务前，agent 就能读到这些信息。卡片状态为 已学习，尚未审核：它是一条供阅读和记忆的指引，不会在 CI 中生效。若要将其变为正式 rule/skill，仍需运行 --draft，然后运行 /propose——人工 gate 保持不变（RULE-02）。

适配器边界（现在构建，之后适配）

以上内容均为确定性流程，且现在即可构建。唯一被隔离的未知项是 harness/failure-flywheel.config.yaml（verified: false）：重复阈值和 taxonomy 都是当前最佳猜测，“从失败中提炼规则”的模型也尚不存在。只要它尚未设置，--draft 就会插入人工 TODO stub，而不是自动生成规则。之后只需编辑这一个文件即可完成最终配置——校准阈值、指定提炼模型，并将 verified: true。

分支

ID	类型	条件	行为	跳过/失败	汇合
B01	conditional_required	错误类别 ≥ recurrence_threshold	W03 --draft，然后执行 W04	低于阈值 → 跳过，仅 report	W04
B02	capability_optional	config verified: true + 存在提炼模型	stub 自动提炼规则，而不是生成 human-TODO	尚未 verified → human-TODO stub（当前默认）	W04

验证与停止

计数和阈值由 failure-flywheel.py 决定（确定性）。有效的 stub = OKF frontmatter + ## Origin，刻意不包含 ## Plan，以便作为种子通过 R7 gate。始终在 W04 停止——绝不会自动晋升。

示例

• 正向： agent 第 N 次编造 API（超过阈值）→ python3 harness/scripts/failure-flywheel.py record invented-api "called nonexistent fetchAll()" → --report 显示 invented-api 并标记为 DRAFT → --draft invented-api 写入 llmwiki/wiki/sources/draft/DDMMYY-failure-invented-api.md，然后停止并等待 /propose。
• 边界/失败： --draft invented-api --date 19/09/2026 → 退出码为 2，并显示明确错误，不会写入日期错误的文件。

相关内容

• harness/scripts/code-logger.py — 相同的按代码、由 Git 忽略的 JSONL、故障时放行的捕获模式。
• llmwiki/skills/dev-loop/propose.md — 此工具所支持的门控。
• llmwiki/skills/dev-loop/build-now-adapt-later.md — 配置所遵循的隔离模式。