project-clarify

Project Clarify

project-clarify は、ユーザーが明示的に呼び出すプロジェクト段階です。1 回の $project-clarify リクエストで 継続的な明確化セッション が開始されます。 各フロンティアラウンドの後、ユーザーは通常どおり返信し、次のフロンティアが 再計算され、再び提示されます。共通理解の確認（または明示的な終了・切り替え） が行われた場合にのみ、project-spec に渡す範囲を限定した引き継ぎが作成されます。 ラウンド間でユーザーが $project-clarify を再度入力する必要はありません。

必須の順序

1. 質問する前に、プロジェクトの事実を調べます。
   docs/agents/light-project.md が存在する場合は、まずその目標、成果物、 ドメインコンテキストの参照先、トラッカーの参照先を読みます。次に、指定された 資料に加えて、関連する README、指示、ソース／テスト／仕様、トラッカーの状態を 調べます。利用できる各事実には安定した参照先を記録し、資料がない場合や 読み取れない場合は、エビデンスの不足として明記します。調査で確定できる事実は ユーザーへの質問にしません。
2. socratic を使ってユーザーの決定を管理します。
   調査済みの事実、不明点、既存の決定、目標を socratic エンジンに渡します。 現在のフロンティア全体をひとつのラウンドとして質問します。複数の独立した質問を、 選択肢、推奨案、必要に応じて簡潔で役立つ理由とともに提示します。原則として、 一度にひとつの質問だけをしてはいけません。
3. 事実や実験に関する不足を意図的に解消します。
   事実の不足がある場合は、どの決定を妨げているのかを明示し、許可された機能呼び出し （light-research、light-prototype、light-to-questionnaire）を台帳に記録します。 実際に読み取った結果パスがない限り、結果を読み取り済みとして扱ってはいけません。 利用できない不足や許可されていない不足は未解決のままにし、そこから派生する決定を フロンティアに含めません。
4. 完了するまで続け、その後、引き継ぎを返して終了します。
   通常のユーザー返信のたびに、再び socratic を使ってフロンティアを再計算し、 次のラウンドを提示します。意味のあるフロンティアが残っていない場合は、共通理解を 確認します。確認後、引き継ぎを返して終了します。通常の返信に対して、 $project-clarify の再呼び出しを求めてはいけません。

引き継ぎの形式

Project clarification handoff
- Target and inspected project facts:
- Evidence not found or not inspected:
- Current goal and constraints:
- Resolved user decisions:
- Open decisions and dependencies:
- Capability call records and results read:
- Current frontier or explicit blocker:
- Recommended next explicit invocation: project-spec | decision-map | none
- Status: ready-for-next-stage | waiting-for-user | blocked

引き継ぎは、デフォルトではメモリ内で返します。次の段階が別のセッションで実行される 可能性がある場合は、.scratch/<feature>/clarify-handoff.md（またはユーザーが指定した 保存先）への保存を提案します。書き込むのはユーザーの確認後に限ります。その後は終了し、 次に何を呼び出すかはユーザーが選びます。

構成とアップグレード

project-clarify → socratic

作業の規模が大きい場合、複数セッションにわたる場合、または依存関係のある決定が多数ある 場合は、$decision-map を推奨して終了します。完全な仕様は project-clarification-contract.md に、 ワークフローと例は WORKFLOW.md と EXAMPLES.md に記載されています。