plannotator-setup-goal

セットアップの目標

構造化された要件整理、ユーザーへのインタビュー、コードベースの調査を通じて、アイデアを goals/<slug>/ に目標パッケージとしてまとめます。

フェーズ

1. 言い換え

ユーザーの希望を、自分の言葉で言い換えて確認します。会話にすでに豊富なコンテキストがある場合は、要約します。目標が曖昧、または簡潔すぎる場合は、理解の手がかりを得るために、コードベースを最低限だけ浅く調査します。2～3文に収めます。続行する前に、ユーザーから確認または修正を受けるまで待ちます。

slug が確定したら、目標ディレクトリを作成します。

mkdir -p goals/<slug>

作業用 JSON ファイルと最終ドキュメントの両方に goals/<slug>/ を使用します。JSON ファイルは出典情報と反復の状態を保持し、Markdown ファイルは人が読める正式な目標パッケージです。

ブラウザーセッションの待機ルール： Plannotator の目標セットアップは、ユーザー主導のブラウザーセッションです。インタビューまたはファクト取得コマンドを起動した後は、ユーザーが送信、終了、または明示的に停止を求めるまで、十分に待ち続けてください。UI がアイドル状態に見える場合やユーザーに時間がかかっている場合でも、閉じたり、強制終了したり、再起動したり、更新したり、2つ目のセッションを開いたりしないでください。状態を更新するためにセッションを閉じて開き直すことは絶対にしないでください。前のセッション終了後に再実行が必要な場合は、作業用 JSON ファイルを更新してから、そのファイルを使って新しいコマンドを起動してください。

任意：最初に深掘りする（1問ずつの詳細なインタビュー）。 簡潔なインタビューバンドルを作成する前に、目標が曖昧な場合、または相互に依存する決定が多い場合は、深掘りを提案し、「最初に深掘りして」とユーザーから求められた場合は実施します。これは任意です。明確で範囲が定まった目標の場合は、深掘りを省略してそのままバンドルに進み、「少数の、より重要度の高い質問をする」というバンドルの方針を損なわないようにします。深掘りする場合は、以下のプロトコルをそのまま実行し、解決した決定事項を、より質の高いインタビューバンドル（フェーズ2）に反映します。深掘りによって範囲が完全に定まった場合は、ファクトシート（フェーズ3）に直接反映します。

この計画のあらゆる側面について、共通理解に至るまで徹底的にインタビューしてください。設計の分岐を一つずつたどり、決定事項間の依存関係を順に解決してください。質問ごとに、推奨する回答も提示してください。

質問は一度に1つずつしてください。

コードベースの調査で答えられる質問については、質問せずにコードベースを調査してください。

2. インタビューバンドル

この目標で生成すべきすべての「事実」を導き出せる、簡潔な質問セットを作成します。ユーザーが Plannotator の目標設定 UI ですばやく回答できるよう、質問をまとめてください。各質問には推奨回答を含め、回答を簡単にできる場合は選択肢を用意します。

明らかな確認質問はしないでください。ユーザーの依頼、会話、またはコードベースの簡単な調査から回答を推測できる場合は、推測して先に進みます。明らかな領域に重要なニュアンスがある場合は、ユーザーに明白なことを言い直してもらうのではなく、推測した回答を選択肢やカスタムの「追加・修正」欄とともに推奨として提示します。

通常、重要となる質問の領域：

• 機能や変更の内容
• 対象ユーザー
• 解決する問題
• 変更される動作
• 成功の判断基準
• 対象範囲と対象外の範囲（事実を明確にするうえで最も重要な領域）
• 考慮すべきエッジケース
• 制約や前例

コードベースを調べれば回答できる質問は、ユーザーに尋ねるのではなくコードベースを調べてください。 ユーザーの判断が実際に必要な質問だけを含めます。明らかなことを網羅的に尋ねるより、数を絞った重要度の高い質問を優先してください。

ユーザーに表示する前に、インタビューバンドルを次の場所に書き込みます。

goals/<slug>/interview.json

{
  "stage": "interview",
  "title": "Short human-readable title",
  "goalSlug": "<slug>",
  "questions": [
    {
      "id": "scope",
      "prompt": "What should be in scope?",
      "description": "Optional clarification.",
      "answerMode": "multi-custom",
      "recommendedAnswer": "Your recommended answer.",
      "recommendedOptionIds": ["ui", "server"],
      "options": [
        { "id": "ui", "label": "UI" },
        { "id": "server", "label": "Server" }
      ],
      "required": true
    }
  ]
}

サポートされている answerMode の値：text、single、multi、custom、single-custom、multi-custom。

監視対象のフォアグラウンドプロセスとして実行し、ブラウザーセッションが完了するまで待ちます。ユーザーが読んだり、編集したり、質問したりしている間、コマンドが停止しているように見える場合があります。そのまま実行し続けてください。

plannotator setup-goal interview goals/<slug>/interview.json --json

コマンドは、送信された回答を含む JSON を標準出力に返します。続行する前に、その結果を変更せずに goals/<slug>/interview-result.json に書き込みます。便利な方法は次のとおりです。

plannotator setup-goal interview goals/<slug>/interview.json --json | tee goals/<slug>/interview-result.json

セッション終了後にユーザーが回答を変更した場合は、記憶を頼りにバンドル全体を作り直すのではなく、interview.json を更新してコマンドを再実行します。セッションが終了された場合は中止し、目標設定が閉じられたことをユーザーに伝えます。

事実の整理に進む前に、すべての回答とメモを注意深く確認してください。

• ユーザーが回答やメモに質問、不確実な点、「よく分からない」、「詳細が必要」などの懸念を書いている場合は、いったん停止してチャットで対応します。ユーザーが十分な情報を得るか、修正版のインタビューバンドルを再実行するまで、事実の整理に進まないでください。
• ユーザーがメモを添えて質問をスキップした場合、そのメモは意図的なフィードバックとして扱い、空欄とはみなしません。メモへの回答、質問の改善、または明記した前提の設定を行ってから進めます。
• ユーザーがメモなしで質問をスキップした場合、未回答でも支障がないときに限り、そのまま進めます。そうでなければ、チャットで必要最小限の追加質問をします。

3. ファクトシート

ファクトとは、ゴールの各成果を簡潔に記述したものです。テストと検証が容易である必要があります。ファクトは、システムの特定の機能や側面の動作を記述することがあります。ファクトが特定の UI や UX を決定することもあります。繰り返しますが、ファクトとは文字通り、自動テストまたは手動テストでテストおよび検証できるあらゆるものです。ファクトの表現は簡潔にしてください。ある意味で、ファクトシートは設計仕様書ですが、より簡潔で、人間のユーザーが容易にイメージし、納得できる言葉を使います。

goals/<slug>/interview-result.json からファクトレビューバンドルを作成します。各ファクトには、自動検証が推奨されるかどうかと、あらかじめ選択された状態を含める必要があります。

ユーザーに表示する前に、ファクトレビューバンドルを書き出します。以前のファクトパスの後に修正する場合は、facts-review.json と facts-result.json から開始し、以前に承認されたファクトを "accepted": true として含め、その状態を保持します。

goals/<slug>/facts-review.json

{
  "stage": "facts",
  "title": "Short human-readable title",
  "goalSlug": "<slug>",
  "facts": [
    {
      "id": "fact-1",
      "text": "The accepted fact text.",
      "accepted": false,
      "removed": false,
      "recommendedAutomatedVerification": true,
      "automatedVerification": true
    }
  ]
}

これを監視対象のフォアグラウンドプロセスとして実行し、ブラウザセッションが終了するまで辛抱強く待ちます。ユーザーがレビュー、編集、または質問をしている間、コマンドはアイドル状態に見えることがありますが、実行したままにしてください：

plannotator setup-goal facts goals/<slug>/facts-review.json --json

コマンドは stdout に JSON を返します。これには承認済み、編集済み、削除済みのファクトと、自動検証の選択が含まれます。その正確な結果を goals/<slug>/facts-result.json に書き出します。便利なパターンは次のとおりです：

plannotator setup-goal facts goals/<slug>/facts-review.json --json | tee goals/<slug>/facts-result.json

goals/<slug>/facts.md を、承認されたファクトのフラットで読みやすいリストとして書き出します。各ファクトは 1 行とし、ファクト単独では明確に記述できない場合にのみ、最小限の注記を追加します。また、goals/<slug>/facts.meta.json を書き出し、承認された各ファクトの id、最終的な text、comment、recommendedAutomatedVerification、automatedVerification の値を保持します。

ユーザーが UI でファクトを編集または削除した場合は、その結果をそのまま適用します。セッションが閉じられた場合は、停止してユーザーにファクトレビューが終了したことを伝えます。

4. プラン

コードベースを調査します。承認された各ファクトに向けた実装パスを発見し、検証します。automatedVerification: true のファクトは、ブロッカーを文書化しない限り、具体的な自動チェックを必要とするものとして扱います。コードを追跡し、関与するファイルとシステムを特定し、リスクと不明点を明らかにします。確信を持てる作業順序が得られるまで洗練させます。

goals/<slug>/plan.md を書き出します：

• ソリューションのアプローチ（簡単に）
• 各ステップが触れるファイルやシステムを含む、順序立てられたステップ
• 各ステップの検証（具体的なコマンドまたはチェック）
• フラグを立てる価値のあるリスクや未解決の疑問

Plannotator でプランをゲートします：

plannotator annotate goals/<slug>/plan.md --gate

拒否された場合は、フィードバックに基づいて修正し、承認されるまで再ゲートします。

5. ゴール出力

goals/<slug>/goal.md を書き出します：

• 明確化されたゴール（1〜3 文）
• 共通理解としての facts.md への参照
• 実行計画としての plan.md への参照
• 完了条件

ユーザーに伝えます：

Done! Launch a goal with `/goal goals/<slug>/goal.md`