frame-a-proposal

提案を構成する — 問題をレビュー可能な RFC にする

ここでのすべての Markdown 操作には、プラットフォームの /open-knowledge スキルが引き続き適用されます（exec／search による読み取り、write／edit による書き込み、リンクは通常の相対 Markdown とし、対象ファイルに対してネイティブの Read／Edit／Grep／cat は使用しません）。このスキルは、その上に提案作成の技法を加えます。つまり、優れた提案に何を含めるか、各セクションをどの順序でまとめていくかを定めます。

proposals/ 内の提案は、設計に関する議論であり、決定でも計画でもありません。選択肢の中から選択することを促し、レビュー担当者が異論を述べるのに十分な材料を提供するためのものです。ファイル名は 0001-feature-name.md です。4 桁のゼロ埋め連番と、ケバブケースのタイトルを組み合わせます。ステータスは draft → fcp → accepted/rejected と遷移します（fcp = 最終コメント期間）。提案が承認されると、decisions/ 内の記録に昇格します。これは別個の、人間が行う作業であり、別のスキルです。

このスキルが防ごうとしている失敗は、問題について合意が得られる前にエージェントが ## Design に飛びつくこと、## Alternatives に藁人形のような代替案を並べること、そして ## Drawbacks を空欄のままにすることです。以下の各ステップには、それを防ぐゲートがあります。

---

必須の実行順序

ハードゲート — 先に進まないでください。 ## Design を書こうとしていて、ステップ 1 の問題設定ゲートを通過していない場合は、停止してください。ゲートを飛ばしています。提案の要点は、解決策を書く前に問題について合意することです。

0. 先行事例を調べる — proposals/ と decisions/ にある、このサブシステムに関する既存の内容を確認します。
1. 問題を設定する — 停止ゲート。 受益者、観測可能な変化、避けられない選択を明確にします。解決策に関する文面を書く前に確認を得ます。
2. 連番を割り当て、proposal テンプレートから作成する。
3. Motivation — 問題、根拠、現時点で影響を受けている人、何もしない場合のコスト、明示的な対象外事項を記載します。
4. Design — 読者が異論を述べられる粒度で提案を記載します。
5. Alternatives — 実際に検討に値するものを少なくとも 2 つ挙げ、それぞれ採用しない理由を記載します。
6. Drawbacks — 正直にコストを記載します。
7. Unresolved questions — 継続中の課題一覧を作り、それぞれに解決担当者と、解決を裏付ける証拠を記載します。
8. リンクと検証。
9. 要約と、fcp に進むために必要なこと。

ホストのタスクシステムに機能がある場合は、ステップ 0〜9 のワークフロータスクを作成してください。セッション中にゲートが飛ばされたことを可視化できます。

---

ステップ 0：先行事例を調べる

問題を設定する前に、このサブシステムについてナレッジベースがすでにどのような決定や提案を行ったかを確認します。承認済みの決定を黙って蒸し返す提案は、最初から受け入れられません。一方、該当する決定を参照し、見直すべき理由を説明する提案は妥当です。

• search({ query: "<subsystem or problem keywords>" }) — 意味検索で、同義語も検出します。
• exec("ls -A proposals/") と exec("ls -A decisions/") — 連番の空き状況と、確定した内容を確認します。
• exec("grep -rln <keyword> proposals/ decisions/") — 同じサブシステムについて記載されたファイルを特定します。
• 最も関連性の高い 1〜3 件について、exec("cat proposals/0003-x.md") を実行し、文書全体とそのバックリンクを読みます。

見つかった内容を分類し、草稿に反映します。

見つかった内容	対応
承認済みの決定がこの領域を対象としている	新しい提案では必ずその決定を引用し（decisions/ 内への Markdown リンクを使用）、Motivation で、何が変わったために再検討するのかを説明します。何も変わっていない場合は、そもそも提案が不要かもしれないことをユーザーに伝えます。
draft/fcp の提案と重複している	ほぼ重複する提案を新たに作るのではなく、既存の提案を拡張するか、置き換えることを提案します。重複する 2 件の提案があると、レビューが分散します。
何も見つからない	そのまま進めます。

ステップ 1：問題を定義する — STOP ゲート

RFC と解決策の文章の寄せ集めを分けるのが、このゲートです。ユーザーが問題の定義を確認するまで、## Design を作成せず、ファイルも作成しないでください。

次の内容をそのまま出力してから、そこで止まり、待機してください。

## Framing (confirm before I draft)

**Beneficiary:** who is worse off today and will be better off if this ships. A named role or user, not "the system" or "us".

**Observable change:** the concrete, checkable difference they will see. "X drops from N to M", "Y becomes possible", "Z stops happening". Not "improve", not "streamline".

**Forced decision:** the one question this proposal makes reviewers answer. If accepting it doesn't commit anyone to anything, it is a report, not a proposal.

**Rough shape:** one sentence on the direction — enough to know we're framing the right problem, not the design itself.

注意事項：

• 「チーム」とは別の受益者を特定できない場合、問題は定義されていません。ドラフトを作成する前に、異議を唱えてください。
• 「観測可能な変化」は反証可能でなければなりません。確認方法を示せないなら、それは結果ではなく活動を説明しています。
• トリガーが曖昧（「キャッシュについて提案すべき」など）な場合は、対象者、きっかけとなる意思決定、その人が観測する変化を明確にしてください。
• 明示的にヘッドレス／非対話型の実行では、問題の定義を示して処理を続けます。ただし、レビュー担当者が問題の定義そのものを却下できるよう、3 つの項目をそのまま「Motivation」に記載してください。

---

ステップ 2：番号を割り当て、テンプレートから作成する

推測せず、一覧を確認してください。 exec("ls -A proposals/") を実行し、既存の NNNN の最大値に 1 を加えて、4 桁になるようゼロ埋めしてください。同じ週に 2 件の提案が作成されるだけで推測した番号は重複します。

ファイル名：NNNN-kebab-title.md（0007-async-export-pipeline.md）。テンプレートから作成してください。これが、## Motivation → ## Design → ## Drawbacks → ## Alternatives → ## Unresolved questions の骨組みとフロントマターを正しく用意する唯一の方法です。

write({ document: { path: "proposals/0007-async-export-pipeline.md", template: "proposal" } })

テンプレートには次のフロントマターが設定されています。手入力で書き直さず、値を入力してください。

type: proposal
description: "..."     # one line: the forced decision, not the feature name
status: draft          # stays draft until a human advances it — see Non-goals
authors: [<user>]
created: YYYY-MM-DD
tags: [proposal]

description には、提案によって判断を迫られる内容を 1 行で設定してください。これは一覧で読者の目に触れる項目です。

---

ステップ 3：Motivation

作成したドキュメントを edit して、## Motivation を記入してください。このセクションだけで内容が完結している必要があります。ここに同意しない読者が「Design」を読むことはありませんし、それで問題ありません。

• 問題を受益者が経験する形で記述してください。解決策がないこととしてではありません。「100MB を超えるエクスポートがタイムアウトし、ユーザーが作業を失う」は、「非同期エクスポートパイプラインがない」より適切です。
• 問題が実在することを示す根拠（指標、繰り返し寄せられる報告、具体的なインシデント）を提示してください。「あったら便利だから」だけを動機とする提案は、動機が不十分です。そのことをユーザーに伝え、根拠となる兆候を 1 つ見つけてください。
• 現在、誰がどのような影響を受けているかを（ステップ 1 の受益者を）明示し、発生頻度も示してください。
• 何もしない場合のコストを示してください。却下する場合も含め、すべての代替案と比較する現状の基準です。何もしなくても本当に問題がないなら、提案は不要かもしれません。
• 対象外事項を明示してください。この提案で意図的に扱わないことを列挙します。対象外事項を定めることで、提案をレビュー可能な範囲に保てます。範囲に上限がない提案は、何に合意するのか誰にも分からないため、承認できません。「Motivation」内に明確な ### Non-goals の行を設け、その下に記載してください。

---

ステップ 4：Design

## Design には、読者が異議を唱えられる粒度で、実際の提案を記述してください。粒度が細かすぎる（すべての関数シグネチャまで記載する）と、レビュー担当者は評価していない設計に追認することになります。抽象的すぎる（「高速化する」など）と、承認できる内容がありません。目標は、知見のある読者がこのセクションを読んで「いや、こうする。その理由は……」と言えることです。

• 仕組み、変更の概要、導入または変更する主要なインターフェースや契約を説明してください。
• 設計を支える重要な選択を明示してください。設計が 1 つの判断（データモデル、境界、順序など）に依存するなら、その判断を示してください。提案全体の本質は、多くの場合その判断にあります。
• ステップ 1 で定めた観測可能な変化が、どのように実現されるかを示してください。設計と受益者を結び付けてください。
• 関連する仕様、ガイド、基盤とする、または再検討する判断へのリンクを、相対パスの Markdown で記載してください（例：[エクスポート境界の決定](./decisions/0004-export-boundary.md)）。
• 実装の細部には立ち入らないでください。その粒度を扱うのは仕様（関連するスキル）の役割であり、提案の役割ではありません。

---

ステップ 5：代替案

## Alternatives に、実際に検討できる選択肢を少なくとも 2 つ記入し、それぞれについて採用しなかった理由を添えます。別の日なら選んでいたかもしれない案も、正直に含めます。進行中の取り組みなら、「何もしない」も含めてください。

それぞれ次の形式にします。

### Alternative: <name>
What it is — one honest paragraph, argued at its best.
Why not — the specific tradeoff that lost, versus the proposed design.

原則：

• 形だけの案は危険信号です。そう明言しましょう。 どの案も明らかに劣っている Alternatives セクションは、作成者が実際の選択肢を検討していないことを示します。そのため、レビュー担当者が提案全体を（当然ながら）信用しなくなります。代替案の本当の利点を説明できないなら、それを退けるほど十分に理解していないということです。
• 「何もしない」も主要な代替案です。その「採用しない理由」は、ステップ 3 の何もしない場合のコストです。
• 適切な数は通常 2～4 件です。1 件だけなら、提案ではなく、決定事項の告知です。

---

ステップ 6：欠点

## Drawbacks には、提案する設計自体の正直なコストを記入します。代替案のコストではありません。

• 欠点のない提案は、完璧なのではなく、検討が不十分です。 現実の設計では必ず何かを犠牲にします。複雑さ、移行作業、新たな障害要因、保守の負担、あるいは選択肢の制限などです。それらを挙げてください。
• 誰が、いつコストを負担するのかを具体的にします。コストを負担する側と恩恵を受ける側は異なる場合があり、レビュー担当者はそのトレードオフを把握する必要があります。
• 本当に許容できる欠点だと考えるなら、隠すのではなく、ここで理由を説明します。明示したうえで受け入れる欠点は、レビュー担当者が後から見つけることになる、記載のない欠点よりも説得力があります。

---

ステップ 7：未解決の質問

## Unresolved questions は免責事項ではなく、現在進行中のバックログとして記入します。各項目では、確信に満ちた文章の中に埋もれさせず、実際に未解決の質問を見える状態に保ちます。

質問ごとに、次のようにします。

- **<question>** — What would resolve it: <the evidence, experiment, or measurement>. Who decides: <role or person>.

• すべての質問に、解決に必要な証拠と決定者を記載します。どちらもない質問は、単なる不安にすぎません。具体化するか、削除してください。
• 承認を妨げる質問は、ここに明記します。これらは fcp 期間中に扱う議題です。
• draft の段階でこのセクションが空でなくても問題ありません。完成しているように見せるために不確実性を隠すことこそが失敗です。未解決の質問を正直に列挙することで、提案を安全にレビューできます。

---

ステップ 8：リンクと検証

準備ができたとユーザーに伝える前に、次を実行します。

• 参照する決定事項、仕様、ガイドはすべて、通常の Markdown 相対リンク（[text](./decisions/0004-x.md)）にします。バッククォートで囲まず、HTML アンカーも使いません。
• 関連性の高いドキュメントを 1～2 件選び、提案へのバックリンクを追加して、提案を見つけやすくします。再検討する採択済みの決定事項、関連仕様、該当するガイドなどです。既存のリンク先を確認するには links({ kind: "backlinks", ... }) を使います。
• audit({ path: "proposals/0007-async-export-pipeline.md" }) の結果が問題なしになるようにします（すべてのリント違反と内部リンク切れを確認します）。指摘事項はすべて修正してください。
• フロントマターを完成させます。type: proposal、1 行の description、status: draft、authors、created、tags: [proposal] を含めてください。
• 5 つの H2 セクションをすべて用意し、内容を記入します。## Motivation、## Design、## Drawbacks、## Alternatives、## Unresolved questions が必要です。セクションが形式上存在していても、Drawbacks が空、または Alternatives が形だけの案で構成されている場合は、このチェックに合格しません。
• status は draft のままにします。あなたがステータスを進めることはありません。Non-goals を参照してください。

---

ステップ 9：要約と fcp への道筋

会話の中で、次の内容を伝えて締めくくります。

## Recap

- Framed: <beneficiary> gets <observable change>; forces the decision <…>.
- Proposal: proposals/NNNN-title.md (status: draft)
- Alternatives weighed: <n>, chosen over them because <one line>.
- Honest drawbacks: <the main one>.
- Open questions still live: <count> — the fcp agenda.

**To advance to `fcp`:** a human moves status draft → fcp and opens the final comment
period. Acceptance (→ accepted, then a record in decisions/) is a human decision, not
mine. If it's rejected, mark status: rejected and keep the doc — the reasoning is the value.

ステータスの更新と提案の採択は、人間が行うことだと明確に伝えます。あなたの役割は、十分に整理され、根拠が正直に示された draft を作成するところまでです。

対象外

• 決定を記録しないでください。 承認されると、提案は decisions/ 内の記録に昇格します。これは別の /record-a-decision スキルの役割であり、人間が承認した後に実行します。このスキルは draft の段階で止まります。
• 実装仕様を書かないでください。 設計レベルの内容にとどめ、構築の詳細には踏み込みません。仕様書の作成には /write-a-spec を使用します。
• 自分の判断で提案を accepted（または fcp）にしないでください。 ステータスを進めるのは人間の役割です。status: draft のままにし、ステータスを進めるために必要なことをまとめて提示してください。
• ステップ 1 の前提整理ゲートを省略しないでください。 問題について合意する前に解決策を書くことこそ、このスキルが防ぐべき失敗です。受益者と解決を迫る判断を確認せずに設計案を作成した場合は、ゲートを飛ばしています。前の段階に戻ってください。
• 代替案に藁人形論法を持ち込んだり、欠点を空欄のままにしたりしないでください。 どちらも提案が十分に検討されていないことを示します。レビュー担当者もそのように受け取ります。