vision

/vision

vision スキルを実行しています。著者が承認できる VISION.md を作成します。プロジェクトの将来に向けた受け入れポリシーを、著者が実際に構築しているものに基づき、対話型レビュー用ボードで回答する仮想シナリオによって磨き上げます。

VISION.md は、コミットする唯一のアラインメント文書です。ボードを一度も見たことのないレビュアーでも、それだけを読んで変更を受け入れるか、異議を唱えるか判断できなければなりません。

これは文章を書く練習ではありません。このファイルの先頭から最後まで、順に従ってください。

ホスト要件

対象リポジトリとその実際の履歴を読み取れる必要があります。

• GitHub 系 CLI（gh、gh-axi）を使ったマージ済み PR の履歴を優先します。
• PR にアクセスできない場合は、デフォルトブランチの git コミット履歴（git log）に切り替えます。タイトルやメッセージからも、著者が構築しているものが分かります。
• 実際の履歴がまったく読み取れない場合に限り、停止してその旨を伝えてください。著者の価値観、PR のタイトル、証拠を決して捏造してはいけません。捏造した証拠に基づくビジョンは、ビジョンがないよりも悪いものです。

レビューの反復には lavish-axi を使い、npx -y lavish-axi から直接実行します。インストールは不要です。まず起動を試し、起動そのものに失敗した場合に限り、ブロッカーとして報告してください。

厳格なルール

1. 雰囲気より証拠を優先します。 草案に含めるすべての原則は、具体的な証拠（名前を挙げた PR やコミット、ファイル、ドキュメント、または著者が VISION.md に承認した推論）にたどれる必要があります。一般的なエンジニアリング上の美徳（「品質を重視する」など）は、履歴が具体的に裏付けていない限り禁止です。
2. まず既存の VISION.md を確認します。 デフォルトブランチに存在する場合は差分モードに切り替え、承認済みのベースラインとして扱います。それより新しい証拠に基づく行単位の変更候補を提案し、対立する別文書は決して作成しません。
3. ビジョンの所有者は著者です。 草案を作成し、厳しく検証し、著者の判断を反映します。承認してはならず、著者に迎合するために仮想シナリオの厳しさを和らげてはならず、著者が述べても実践してもいない原則を反映してはなりません。
4. ビジョンは受け入れポリシーです。 未来の読者が、人間でもエージェントでも、VISION.md だけを使って具体的な変更を判断できるよう、明示的な非目標を含め、検証可能な受け入れ基準と拒否基準を現在形の宣言文で記述します。
5. 答えやすい仮想シナリオは禁止です。 それぞれに、賛否どちらにも妥当な根拠がある、実際の対立点を設定し、両方の立場を最も説得力のある形で示します。著者の回答を予測できる場合は、そのシナリオを差し替えてください。
6. レビューの反復には lavish-axi を使い、同梱テンプレートを使用します。 草案と仮想シナリオは、assets/review-template.html と assets/review.css から作成した単一のボードとして提示します。そのまま使用し、白い紙に黒いインクで文学作品のように組み、草案全体を常に完全に表示し、カードスタック内で一度に 1 つの仮想シナリオを提示します。テンプレートのスロットを埋め、スタイルや構成を変更したり、別のレビュー画面で代用したりしてはなりません。
7. 複数回に分けて反復し、すべての編集を追跡します。 著者の各判断を変更履歴の名前付き編集に対応させます。回答によってテキストがどう変わったかを、著者が正確に確認できなければなりません。
8. 書式。 1 行につき 1 文にします。通常のハイフンを使い、em ダッシュは使いません。ロードマップ、機能一覧、マーケティング調の表現は禁止です。
9. VISION.md は唯一のアラインメント文書です。 著者の推論は、適切な形式で、重要な箇所の文章に反映します。仮想シナリオやボードの記録を VISION.md にコピーしてはなりません。対象リポジトリに回答ファイルを書いたり、残したり、その場所を示したりしてはなりません。ボードの記録はツールのスクラッチ領域に保存できますが、決してコミットしてはなりません。

パイプライン

ステップ 0 - 対象と著者を特定する

• 対象リポジトリ：特に指定がない場合は現在の作業ディレクトリ、または明示された owner/repo です。
• 著者：ビジョンの著者となる人物です。特に指定がない場合はリポジトリのオーナーです。その人物のマージ済みの作業を証拠の基盤とします。
• 対象または著者が本当に曖昧な場合は、短い質問を 1 つだけします。

ステップ 1 - パターンを学ぶ

VISION.md には安定した構成があります。草案は次の構成に沿っているか確認してください。

• アイデンティティを示す冒頭：「X は……するために存在します」、誰に役立つのか、そして「X が担うのは、ただ 1 つのことです。それは……です」。
• 3〜6 個の原則セクション。簡潔で断定的な見出しを付け、それぞれに検証可能な現在形の約束と、行わないことを記します。
• 具体的に明示された非目標（「これは CI システムではなく、……でもありません」など）。
• 締めくくりの 2 つの判定基準：「変更が方針に沿うのは……の場合です」と「変更には抵抗すべきなのは……の場合です」。実際の PR に適用できるほど具体的にします。
• 文体：断定的、現在形、マーケティング表現なし。長さは 1〜2 ページ（40〜70 行）。執筆者の考えは、重要な箇所で、最も自然に読める形式で本文に含めます。尋ねた質問を並べた記録のような形式にはしません。

執筆者が参考となるビジョンを挙げている場合は、それらを読み、構成、文体、長さに注目してください。

ステップ 2 - 既存のビジョンを確認する

• デフォルトブランチに VISION.md がある場合：差分モード（ハードルール 2）です。履歴と照らしてその古さを確認し、証拠に裏付けられた追加・編集候補のみを提案します。それぞれ単独で採用できる内容にしてください。
• ない場合：ゼロから作成するモードです。
• VISION-ANSWERS.md または回答をまとめた関連ファイルが存在する場合は、草案を作成する前に移行を行います。不足している考えを VISION.md に取り込み、回答ファイルを削除し、そのファイルへの参照も削除してください。

ステップ 3 - 証拠を掘り起こす

• リポジトリを分析します：README に記載されたアイデンティティ、アーキテクチャ、明示された非目標、拒否の方針、テストの規律を確認します。
• 履歴を調べます：執筆者がマージした PR のタイトルを一覧にし、30〜100 件を目安にします。範囲全体に分散した 8〜15 件の PR について、本文をすべて読みます（例：gh pr list --author <owner> --state merged --limit 100、または gh-axi の同等コマンド）。PR にアクセスできない場合は、代わりにデフォルトブランチのコミット履歴をたどります（git log --author=<owner>）。同じ傾向が読み取れるよう、コミットメッセージを確認します。
• 繰り返し現れる、行動に表れた価値観を抽出します：何を作るのか、何を拒むのか、どのような不具合を根本から修正するのか、意図を述べる際に執筆者がどのような表現を使うのかを確認します。
• 非公開の証拠シートを作成します：「価値観 → 裏付けとなる PR、コミット、またはファイル」の対応をまとめます。このシートを、草案の各行の根拠とします。

ステップ 4 - 草案を作成する

• ステップ 1 の構成と、以下の出力テンプレートに従います。
• すべての行を証拠シートに対応させます。長さの目安は 40〜70 行です。
• 差分モードでは、変更されていないベースラインと、根拠を添えた追加・編集候補の番号付きリストを出力します。

ステップ 5 - 仮想の変更案を設計する

• ビジョンごとに 8〜12 件の具体的な変更案を作成し、草案の判断が分かれる点を狙います。次の分類を参考にしてください：
  • 執筆者に依頼されそうな、魅力的だが方針にそぐわない機能。
  • 原則同士の衝突（シンプルさと機能性、安全性と速度、汎用性と焦点、コストと品質）。
  • 一見妥当な一歩によって、次の一歩まで当たり前になってしまう滑りやすい坂道。
  • 範囲の拡大（新しいユーザー、コンテンツの種類、ホスト、チーム）。
  • 草案で答えが明らかになっていない、アイデンティティに関する問い。
• 各仮想案は、ID、タイトル、具体的な提案（2〜4 文）、検証する原則（草案から引用）、そして答えが自明でない理由（双方の主張を強く示す）で構成します。
• 品質基準：答えを予測できる仮想案は削除し、別の案に置き換えてください。

ステップ 6 - レビューループ（同梱テンプレートを使った lavish-axi）

• assets/review-template.html と assets/review.css をツールのスクラッチ領域（対象リポジトリではありません）にコピーし、テンプレート内で指定された箇所だけを記入します。プロジェクト名、実行メモ、DRAFT の全文、CARDS 配列（カードごとの id、タイトル、提案、検証対象の原則、両方の立場を擁護するスティールマン）です。
• ほかは何も変更しません。テンプレートには、左側に DRAFT 全文、右側にカードを 1 枚ずつ表示、スティールマンの全文表示、カードごとに判定を 1 つずつキューに追加するという所定の構成がすでにあります。そのため、定型文を書き換えたり、実行ごとにスタイルを変更したりする必要はありません。
• npx -y lavish-axi <board.html> で起動して URL を報告し、その後 npx -y lavish-axi poll <board.html> で待機します。回答はキューに追加された判定として届きます。
• 各バッチを受け取ったら、著者の理由を DRAFT に反映し、VISION.md だけで賛成・反対を判定できる状態にします。読みやすい形式で記述し、仮定の内容、カード ID、ボードのやり取りの記録はコピーしません。ボードの HTML と poll のログはツールのスクラッチ領域に残してかまいません。対象リポジトリには回答ファイルを決して書き込みません。ボードはその場で更新し（新しい DRAFT の文章、残りのカード）、poll --agent-reply で判定ごとに変更履歴の行を返信します（「H-7 は却下 → 権限のセクションが……で始まるよう変更」）。
• 著者が承認するかセッションを終了するまで続けます。著者に代わって承認してはいけません。沈黙を承認とみなしてはいけません。

ステップ 7 - 完了

• 提出するもの：承認済みの VISION.md の本文（または承認済みの差分）。それがアラインメントを判断するための全情報です。
• 対象リポジトリに VISION-ANSWERS.md やほかの回答ファイルがないこと、README と AGENTS.md がそれらを参照していないことを確認します。
• 回答ファイルを残すよう著者に伝えてはいけません。変更履歴はレビューループの返信に記録されており、コミット対象の成果物ではありません。

出力テンプレート（ゼロから作成するモード）

# ビジョン

`{project}` は、{プロジェクトが存在する理由を一文で}するために存在します。
{具体的なユーザー}に役立ち、ユーザーの入力を{何に変換するか}します。
所有する対象は 1 つだけです。それは{単一の対象領域}です。

## {原則のセクション、3～6 個}

{宣言的で、検証可能な現在形の文を 1 行に 1 文ずつ記述します。}
{何を歓迎し、何を拒否するのか、またその理由を明確にします。}

## スコープ

{このプロジェクトが対象としないものを具体的に示します。}
{該当する場合、個人的な情報や非公開の情報をどこに保管するかを示します。}
{該当する場合、リポジトリが自らの基準をどう守るかを示します。}

{検証可能な肯定的基準}を満たす変更は、このビジョンに沿っています。
{検証可能な否定的基準}に当てはまる変更には、異議を唱えるべきです。

事前チェックリスト（下書き作成前）

• 対象リポジトリと著者を特定した
• 既存の VISION.md を確認した（モードを選択済み）
• 既存の VISION-ANSWERS.md を移行した、または存在しないことを確認した
• 実際の PR またはコミットをもとに根拠資料を作成した（根拠を捏造していない）

承認前チェックリスト（著者の承認を得る前）

• 下書きの各行が、根拠資料または VISION.md に反映された著者の考えに基づいている
• 仮定のケースが 8～12 個あり、予測可能なものはなく、両方の立場をスティールマンしている
• 著者による各判定の理由が下書きに反映され、レビュー返信に根拠をたどれる変更履歴の行がある
• VISION.md だけで賛成・反対を判定できる
• 対象リポジトリに回答ファイルを書き込んだり、残したり、参照したりしていない

移行（既存の VISION-ANSWERS.md）

対象のリポジトリに VISION-ANSWERS.md（またはビジョンと同じ場所にある補足回答ファイルや議事録ファイル）がすでにある場合は、次の手順に従います。

1. 内容を読み、著者の考えを抽出します。仮定の話、カード ID、判定ラベル、スティールマン、ボードの議事録は破棄します。
2. VISION.md にない考えを、最も自然な形で本文に取り込みます。すでに反映されている内容は省きます。質問ごとに項目を設けるのではなく、重複する回答はまとめます。
3. 対象のリポジトリから回答ファイルを削除します。
4. AGENTS.md、README、その他のコミット済みドキュメントから、そのファイルへの参照を削除します。

長さの目安：VISION.md は1〜2ページ（目標は40〜70行）に収め、記録簿のようにしないでください。内容を取り込むとQ&Aの寄せ集めになってしまう場合は、さらに要点を絞ります。ボードを見たことがないレビュアーが、VISION.md だけを読んで具体的な変更を受け入れるかどうか判断できることが基準です。