clarify-requirements

要件の明確化

事前計画ワークフロー：requirements-generator を呼び出す前に曖昧さを特定し、解消します。

ハーネスの確認

../nextstage-harness/references/harness-discovery.md と ../nextstage-harness/references/artifact-layout.md を参照してください。

{product_root} を解決します： リポジトリのエントリにある AGENTS.md を読みます。文書化されたアンカーを優先してください。パスが存在しない場合、開いているワークスペースの外にある場合、または別のクローンを指している場合は、AGENTS.md を含むディレクトリを使用してください。

スタックとアーキテクチャに関する質問は、スタック検出の対象です。このスキルの対象ではありません。

使用するタイミング

• ユーザーのスコープが曖昧、または不完全な場合
• 用語が曖昧な場合（ダッシュボード、連携、通知システムなど）
• 既存のドキュメントがない新しいシステムの初回バージョンの場合
• オーケストレーターがスコープ不足（3 段落未満、または曖昧な用語がある）と判断した場合

ワークフロー

Step 0 — ブラウンフィールドの確認（分析前）

このステップが完了するまで、アプリケーションのソースコードを grep したり、調査したりしないでください。

1. {product_root}/docs/context/brownfield-map.md を確認します。
2. {product_root} 配下にブラウンフィールドの兆候がないか検出します：backend/、frontend/、src/、app/、または同等のアプリケーションコード（ドキュメントのみのリポジトリは除く）。
3. ブラウンフィールドの兆候があり、brownfield-map.md がない場合：
   • 停止します。まだ確認の質問をしてはいけません。
   • bootstrap-brownfield を呼び出し、{product_root}/docs/context/brownfield-map.md を作成します。
   • スコープを絞り込む前に、ブラウンフィールドのコンテキストが必要だったことをユーザーに簡潔に伝えます。
   • マップファイルが存在したら、このスキルの Step 0.4（更新確認ゲート）から再開します。
4. グリーンフィールドの場合（アプリケーションコードがない）— ブートストラップを省略し、Step 1 に進みます。
5. brownfield-map.md がすでにある場合 — スコープ分析の前に Step 0.4 を実行します。

Step 0.4 — ブラウンフィールド更新確認ゲート（人間による確認が必須）

停止します。人間から返信があるまで Step 1 に進んではいけません。

1. {product_root}/docs/context/brownfield-map.md を読みます。
2. ファイルヘッダーにある **Date:** 行からマップの日付を抽出します。ない場合は date unknown と記載します。
3. 次のゲートを人間に提示します。

Brownfield map found: docs/context/brownfield-map.md
Last updated: {date from file, or "date unknown"}

Before clarifying this version's scope, do you want to refresh the brownfield map
(re-scan codebase with bootstrap-brownfield) or keep the existing map?

Reply with one of:
- refresh — update brownfield-map.md, then continue clarification
- keep — use the existing map as-is and continue clarification

4. 明示的な返信を待ちます。 有効な回答：refresh / keep（または自然言語での明確な同等の回答）。
5. マップが新しそうだから、計画を急ぐ必要があるから、またはユーザーがすでに説明文を貼り付けたからといって、keep と決めつけてはいけません。
6. refresh の場合： bootstrap-brownfield を呼び出して（既存のファイルを更新し）、新しいマップを使用して Step 1 に進みます。
7. keep の場合： セッションコンテキストに、人間がマップの日付 {date} を承認したことを記録し、既存のファイルを使用して Step 1 に進みます。
8. 返信が曖昧な場合：もう一度だけ確認します。refresh または keep が明確になるまで Step 1 を開始してはいけません。

ゲートの解決後、{product_root}/docs/context/system-reverse-spec.md があれば、それも読みます。

Step 1 より前に読み取りが許可されているもの（ブラウンフィールドの場合）：ユーザーのスコープファイル、brownfield-map.md、system-reverse-spec.md、{harness_root}/rules/architecture-rules.md、有効なバージョンの {product_root}/docs/versions/{version_san}/ 配下のファイル。

Step 1 より前に禁止されていること： 「曖昧さを減らす」ために backend/、frontend/、または src/ で場当たり的な grep やコード検索を行うこと、マップがあるのに Step 0.4 を省略すること。

Step 1 — 元のスコープを分析する

ユーザーの説明（および Step 0 が適用された場合はブラウンフィールドのコンテキスト）を読みます。曖昧な点を洗い出します。

カテゴリ	例
アクター	「ユーザーが X を行う」—どの役割か？
データ範囲	フィールド、ページネーション、フィルターの一覧は？
連携	REST、Webhook、認証方式は？
マルチテナント	複数企業間の分離は？
ビジネスルール	具体的にどの検証を行うか？
状態のライフサイクル	許可される遷移は？
スコープの制限	このバージョンに含めるもの、含めないものは？
パフォーマンス	ボリューム、同時実行数、SLA は？
セキュリティ	認証は必要か、役割ごとの権限は？

既存のものを把握するにはブラウンフィールドマップを使用し、ユーザーにはバージョンで変更または追加する内容だけを尋ねます。

Step 2 — 質問する

• 1回につき最大5つの質問
• 正確な機能生成を妨げる要因を優先します
• 可能な場合は、関連する質問をまとめます
• 平易な言葉で、番号付きにし、各質問だけで内容が理解できるようにします

次を提示します。

Before generating requirements, I need to clarify a few points:

1. [actor question]
2. [data scope]
...

Reply in free form. I will proceed with requirements once I have these answers.

Step 3 — 回答を整理する

回答を受け取った後：

1. 短い要約（3～5項目）で理解を確認します
2. 「要件の生成に進んでもよろしいですか？」と尋ねます
3. はい、または修正の回答を待ちます
4. 確認のやり取りは最大1回です。それでも不明な点がある場合は、妥当な前提を「前提条件」として記録します

Step 4 — requirements-generator に引き継ぐ

補足したコンテキストをまとめます。

## Original scope (user-provided):

[original text]

## Brownfield context (if applicable):

[Summary from brownfield-map.md — modules and constraints relevant to this version]
[Brownfield gate: human chose refresh | keep on {date shown in gate}]

## Clarifications obtained:

1. Question: [...]
   Answer: [...]

## Confirmed premises:

- [Premise 1]
- [Premise 2]

このドキュメントを requirements-generator への入力として渡します。ここでは requirements.md を作成しないでください。

重要なルール

• マップのないブラウンフィールド： 最初に bootstrap-brownfield を実行します。コードベースを grep して代用することは決してしないでください
• マップのあるブラウンフィールド： Step 0.4 の確認は必須です。最後にマップが更新された日付を表示し、明示的な refresh または keep の指示を待ちます。指示を推測してはいけません
• 質問は最大1ラウンドです。その後は慎重に前提を置き、記録します
• このワークフローでは要件ドキュメントを作成しません
• 技術スタックやアーキテクチャに関する質問は禁止です。技術スタックプロファイル、プロジェクトルール、ブラウンフィールドマップに委ねます
• 重要な点についてユーザーが「わからない」と回答した場合は、最小限かつ最も安全な範囲を想定し、その旨を記録します

統合

planning start → [brownfield + no map?] → bootstrap-brownfield → [brownfield refresh gate] → clarify-requirements → requirements-generator → Gate 1

ブラウンフィールドの更新確認：brownfield-map.md の日付を確認した後、人間が refresh または keep を選択します。

関連スキル

• bootstrap-brownfield — コードが存在し、brownfield-map.md がない場合に必要な前提作業
• requirements-generator — 確認後の次のステップ
• architecture-rules-generator — architecture-rules.md がまだひな形の場合の憲章（このスキルとは別）