failure-flywheel

スキル：failure-flywheel

繰り返し発生する失敗をルールに変えます。コードで記録し、決定論的にカウントし、人間が承認するためのスタブを作成します。自動昇格は決して行いません。

概要

目的とコンテキスト

• 目的： エージェントの繰り返し発生する失敗をガードレールに変えます。失敗をコードで記録し、分類体系に基づいて決定論的にカウントし、あるクラスの失敗がしきい値を超えたら、提案→ゲートのフローにルール／スキルの提案スタブを作成します。
• 使用するタイミング：
  • 再発する可能性のある形でタスクが失敗したとき（API をでっち上げた、テストを壊した、ルールを無視した、作り込みすぎた）。忘れずにカウントできるよう、記録します。
  • 定期的に（セッションの終了時、または失敗が N 回発生するごと）：--report を使って、どの失敗クラスが最も多く繰り返されているかを確認します。
  • あるクラスが再発しきい値を超えたとき：--draft <category> で候補ルールのたたき台を作り、その後 /propose を実行して完成させます。
  • ユーザーが「この失敗を記録して」「このミスを記録して」「なぜこれが何度も起きるのか」「失敗をルールに変えて」「失敗の分類体系」「何が繰り返し壊れているのか」と言った場合、または /failure-flywheel を実行した場合。
• 対象外： ルールを自動で作成するためには使わないでください。このスキルはゲートへの提案を作成するものであり、人間が必ず承認します。ルールの内容を自動で蒸留しないでください（判断が必要な 10% は人間と /propose が担います）。

メンタルモデル

失敗 → 記録(category) → failures.jsonl → --report（グループ化・件数・ランキング）→ クラス ≥ recurrence_threshold → --draft スタブ → /propose → 人間による承認ゲート。Hamel：作成 → ラベル付け → 修正 → 繰り返し。機械が 90% の機械的な作業を行い、「本当のルールは何か」という 10% は人間が判断します。

入力と出力の契約

	フィールド	必須？	意味
In	<category> + "<summary>"	はい（record）	最も近い分類クラス。未知の category も記録されますが、report でフラグが付けられます
In	--detail "..."	いいえ	追加の詳細
In	--date YYYY-MM-DD	いいえ（draft）	ISO 形式のみ。既定値は 2026-06-29。形式が不正な場合 → exit 2
In	harness/failure-flywheel.config.yaml	はい	しきい値 + 分類体系（アダプター、verified: false）
Out	failures.jsonl の行	はい（record）	ローカルの履歴。gitignore 対象
Out	ランキング	はい（report）	クラスごとの件数、初回／最終確認日時、DRAFT のクラス
Out	llmwiki/wiki/sources/draft/DDMMYY-failure-<category>.md	しきい値を満たした場合のみ	スタブ（OKF frontmatter と ## Origin を含み、## Plan は含まない）—人間の対応待ちで停止

ルールと機能

• RULE-01 (MUST)：失敗の記録はフェイルオープンにします。失敗を記録しても、セッションを中断させてはいけません。
• RULE-02 (MUST)：自動昇格は決して行いません。--draft は /propose のたたき台を作成し、人間が承認します。
• RULE-03 (MUST)：決定性を保つため、ドラフトファイルの日付は固定です（--date、既定値は 2026-06-29、ISO の YYYY-MM-DD のみ — wiki のファイル名で使う DDMMYY 形式ではありません）。実際の使用時には今日の日付を指定できます。不正な --date は、既定値に黙ってフォールバックするのではなく、明確なエラーを表示して exit 2 で終了します（同じ黙示的なフォールバックが原因で誤った日付のドラフトファイルが作成された後、2026-07-20 に修正）。
• RULE-04 (MUST)：しきい値や分類体系を設定ファイル以外の場所にハードコードしてはいけません。設定ファイルがアダプターです。
• 機能：ローカルの失敗履歴に追記する、しきい値／分類体系の設定を読み取る、wiki のドラフトにスタブファイルを 1 つ書き込む。ネットワークへのアクセスは行わず、実際のルール／スキルも変更しません。

失敗時の境界

• 失敗の記録に失敗 → フェイルオープン（セッションを壊さない）、処理を止めません。
• --draft のクラスがしきい値未満 → スタブを書き込みません（狭義の blocked。現在の件数を報告します）。
• --date の形式が不正 → failed。exit 2 で終了し、明確なメッセージを表示します。
• Config に verified: false が残っている → スタブには人間向けの TODO のみを含め、ルールは自動作成しません（意図的な partial）。

使い方

メインワークフロー

ステップ	種別	入力	アクション	出力／終了	失敗／次の処理
W01	副作用あり	発生したばかりの失敗	最も近い分類体系の下に record <category> "<summary>" を記録	jsonl の行	未知のカテゴリ → 記録してレポートにフラグを付ける
W02	決定的	failures.jsonl + config	--report でランキングを確認	しきい値以上のクラスに DRAFT のマーク	条件を満たすクラスがない → 停止
W03	副作用あり	しきい値を満たすクラス	--draft <category> でスタブを作成	ドラフトスタブファイル	しきい値未満／--date が不正 → 停止
W04	判断	スタブ	人間の対応を待って停止。人間が /propose を実行し、ゲート付きのルール／スキルにする	完成した提案	人間が却下 → スタブを維持

各ステップの詳細（W01～W04の信頼できる情報源）：

フライホイール（Hamel：作成 -> ラベル付け -> 修正 -> 繰り返し）

時間のかかる人間の作業は、「同じミスが繰り返されていることに気づき、それをルールにする」ことです。これにより、機械的に処理できる90％（記録 + 分類体系 + 集計 + 足場作成）を決定的にし、判断が必要な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. 失敗が起きたら、最も近い分類カテゴリの下に record で記録します（config を参照）。記録は決してブロックされません。未登録のカテゴリも記録され、--report にフラグが表示されます。
2. --report を実行してランキングを確認します。DRAFT とマークされたクラスは、しきい値以上に再発しています。
3. 条件を満たすクラスに対して --draft <category> を実行します。有効なドラフト STUB（OKF frontmatter + ## Origin）が書き込まれます。R7 ゲートをシードとして通過させるため、意図的に ## Plan は含めません。内容には、テンプレート化された「TODO: これらN件の失敗からルールを抽出する」と失敗の一覧が含まれます。
4. スタブはここで停止し、あなたの対応を待ちます。/propose を実行して、完全なゲート付きルール／スキルにしてください。FailureFlywheel が自動で昇格させることはありません。ゲートは人間が維持します。

次回に向けた指示としてまとめる（ユーザー 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 フックは、各セッションの開始時に最新のカード5枚を毎回表示します（🧯 [学習済み] セクション）。そのため、次回エージェントが同種の作業を始める前に読み取れます。カードの状態は 学習済み、未承認 です。読み返して覚えるための指示であり、CI で強制されることはありません。正式なルール／スキルにするには、引き続き --draft の後に /propose を実行する必要があります。人間によるゲートは維持されます（RULE-02）。

アダプター境界（今すぐ構築し、後で適応する）

上記はすべて決定的で、今すぐ構築されています。隔離されている未知の要素は harness/failure-flywheel.config.yaml（verified: false）だけです。再発のしきい値と分類体系は最善の推定値であり、「失敗を抽出してルールにする」モデルはまだありません。未設定の間は、--draft はルールを自動作成せず、人間向けTODOを含むスタブを挿入します。後でこのファイルだけを編集すれば確定できます。しきい値を調整し、抽出モデルを指定して、verified: true に切り替えます。

分岐

ID	種類	条件	動作	スキップ／失敗	合流先
B01	必須条件付き	エラークラス ≥ recurrence_threshold	W03 --draft を実行し、次に W04	しきい値未満 → スキップし、レポートのみ	W04
B02	任意機能	config の verified: true + 抽出モデルあり	人間向けTODOの代わりに、ルールを自動抽出するスタブを作成	未検証 → 人間向けTODOスタブ（現在のデフォルト）	W04

検証と停止

集計としきい値は failure-flywheel.py が決定します（完全に決定的）。有効なスタブ = OKF frontmatter + ## Origin。シードとしてR7ゲートを通過するよう、意図的に ## Plan は含めません。常にW04で停止し、自動昇格は決して行いません。

例

• 成功例： エージェントが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 — この設定が従う隔離パターンです。