ajitta/know-your-unknowns

Unknowns Loop — 強力なモデルと協働するための運用ループ

基本原則: 強力なモデルにおけるボトルネックはモデル自身ではなく、ユーザーが計画（地図）を現実（領域）に一致させ続ける能力である。このギャップこそが未知の領域である。 良いプロンプトを1つ与えることよりも、探索 → 質問 → 計画 → 実装 → 逸脱を記録 → 検証というループを設計することの方が重要である。 出典: 11の「Know your unknowns」の例; このループ自体はプラグイン拡張機能 — 詳細は skills/loop/references/talk-source.md を参照。

出力: Artifactツール → .unknowns/<YYYY-MM-DD>-loop-<slug>.html → Markdown。 各ステージのアーティファクトは自身のスキルの反応制御を保持し、ループ自体の制御はステージごとのチェックポイントであり、これが .unknowns/loop.json トラッカーに集約される。 詳細: skills/loop/references/output-routing.md

ステップ (10 — 規模に応じて縮小)

1. 価値と完了条件を定義する

開始前にユーザーと合意する: 目的 / ユーザーにとっての価値 / 完了条件 / 決して壊してはならない既存の動作 / 許容されるコストと変更範囲。 成功基準がなければ、実装量を進捗と誤認する。

2. 盲点調査 → /unknowns:blindspot (コピーインストールの場合は /blindspot)

調査のみ、実装は行わない。未知の未知、競合点、回帰リスクを発見し、改善されたプロンプトを生成する。ドメイン自体 に不慣れな場合（用語が不明なためにリクエストが曖昧な場合）は、併せて /unknowns:teach-me を実行する。

3. インタビュー → /unknowns:interview

アーキテクチャを変える質問を最初に、1ラウンド最大4つまで。

4. ソリューションの探索と具体化 (必要に応じて)

• 何をすべきか 未決定 → /unknowns:brainstorm (ソリューション空間マップ)
• どうあるべきか を言葉で説明できない → /unknowns:prototypes (発散的なモックアップ)
• 模倣すべき例 がある → /unknowns:reference (リファレンス分析)

5. リスクのある仮説のプロトタイプ (必要に応じて)

完全な実装の前に、最も不確実な技術的仮定のみを検証する最小限のプロトタイプ を構築する。最初に仮定と成功/失敗基準を明示する。

6. 計画 → /unknowns:plan

実行順序ではなく 修正確率 でソートされた調整可能な計画。ユーザーの入力が必要な決定（スキーマ、インターフェース、UX契約）は上位に配置する。

7. 実装 + 逸脱ログ → /unknowns:notes のルールを適用

計画にないものはすべてログに記録する。アーキテクチャ、ユーザーに見える動作、データ、セキュリティに影響する決定については停止して問い合わせる。会話が圧縮された場合は、実装を再開する前に /unknowns:notes (およびこのスキルのステップ一覧) を再呼び出しする。

8. 独立した検証 → unknowns:independent-reviewer エージェント

エージェントツールで生成する (subagent_type: unknowns:independent-reviewer)。フォークや /subtask は絶対に使用しない — それらは実装者のコンテキストを継承してしまい、このステップが排除しようとしているものそのものである。エージェントには以下を渡す: 完了条件 (ステップ1)、承認済み計画 (ステップ6)、IMPLEMENTATION_NOTES.md のパス、差分範囲/変更ファイル、テストの実行方法。実装者自身のサマリーは絶対に渡さない。

9. 理解確認と引き継ぎ → /unknowns:quiz

ユーザーがこの作業をPRや引き継ぎで説明できることを確認する。レビュアーやステークホルダーの 承認 が必要な場合は、/unknowns:buy-in ドキュメントも生成する。

10. 価値レビュー

コードの品質ではなく、実際の価値で判断する: 誰の問題が縮小したか、どの程度/どのように速くなったか、使われないかもしれない理由、メトリクス、削除条件。構築は簡単だが、価値を生み出すのは依然として難しい。 1つのスコアカード行を取得して終了する — ユーザーに、これまで知らなかったことが明らかになったか、それが意思決定を変えたかを尋ね、その行を .unknowns/scorecard.md に追記する。その2つの質問に対して代わりに回答してはならない。両方の回答が「いいえ」の場合でも行を記述する。詳細: skills/loop/references/scorecard.md

規模縮小基準

• 小さな修正 (1–2ファイル、明確な仕様): ステップ7のルール（メモ）のみ — ループは不要。
• 中程度の作業: 1 (1回のやり取り) → 2 → 3 → 6 → 7 → 9。
• 大規模または不慣れな作業: すべてのステップ。ステップ4と5は必要に応じてのみ実行。
• ステップ1はすべての階層で実行する。階層が不明な場合はユーザーに確認し、選択を記録する。

ループステータス (圧縮、/resume、新規セッションでも保持)

.unknowns/loop.json を保持 — {task, tier, stage, decisions[], artifacts[]} — 各ステージの境界で書き換える。各ステージは、1つのAskUserQuestionチェックポイント（続行 / スキップ / 停止）で終了し、その回答をそこに記録する。

• 引数 status: ファイルを読み込み、階層、現在のステージ、残りステップを報告する。
• 引数 resume: ファイルを読み込み、記録されたステージから続行する。
• その他の引数テキストはタスクの説明として扱う。
• 引数なし: .unknowns/loop.json が存在すればそれを再開し、存在しなければ最初にタスクを尋ねる。

運用原則（圧縮版）

1. 目的を定義する。 2. 実装前に盲点を見つける。 3. モデルに質問させる。 4. 言葉の代わりにリファレンスとプロトタイプを与える。 5. 計画を修正確率でソートする。 6. 未知の領域と計画の逸脱を記録する。 7. テストと独立したレビューで検証する。 8. ユーザーが結果を説明できることを確認する。 9. 成果物はリアクション可能な形式で提供する。 10. コードの量ではなく実際の価値を測定する。