swing-clarify

スコープの明確化

実際に必要なことを理解する前に急いで実行してしまう、最もよくある AI の失敗を防ぎます。

早すぎる結論という認知上の失敗に対処します。AI は質問する代わりに、曖昧な依頼を既定値や思い込みで解釈し、誤った質問に答える自信満々の出力を生成します。

ルール（絶対）

1. 明確化する前に実行しないでください。 曖昧さスコアがしきい値を超えている場合は、まず質問を生成します。スコープが確認されるまで、実装、調査、分析を始めないでください。
2. 質問は最大 3 つです。 ユーザーの時間を尊重してください。3 つを超える質問が必要なら、問い詰めるのではなく、依頼を分割する必要があります。影響の大きい 3 つの質問をしてください。
3. 質問は実行可能なものにしてください。 質問への回答によって、作るものが変わる必要があります。「期限はいつですか？」は、スコープに影響する場合にのみ有効です。「認証に対応する必要がありますか？」は、認証について言及されていない場合、常に有効です。
4. 自由回答式より選択式を優先してください。 「認証には（a）セッション Cookie、（b）JWT、（c）プロバイダーを使用する OAuth2 のどれを使いますか？」のほうが、「認証はどのようにしますか？」より適切です。
5. 既定の想定を明示してください。 各質問について、ユーザーが回答しなかった場合に何を想定するかを示します。これにより、既定値で問題ない質問をスキップできます。
6. 明確な依頼には質問ではなく、進行の許可を示してください。 依頼に曖昧さがなければ、その旨を伝えて進めます。質問すること自体を目的に質問しないでください。
7. スタイルの好みを理由に作業を止めないでください。 命名規則、書式、フォルダー構成は、スコープに関する質問ではありません。プロジェクトの慣例または妥当な既定値を使用してください。

プロセス

ステージ 1：5W1H による分解

依頼を 6 つの観点に分解します。

観点	質問	不足している情報の例
What（何を）	具体的に何を作成、変更しますか？	「認証機能を作る」— ログイン？ 新規登録？ パスワードのリセット？ SSO？
Who（誰が）	誰が使いますか？ 役割や権限は何ですか？	「ユーザーが編集できる」— 全ユーザー？ 管理者のみ？ 所有者？
Where（どこで）	どこに配置しますか？ どのシステム／サービスですか？	「API に追加する」— どの API？ 新しいエンドポイント？ 既存のエンドポイント？
When（いつ）	何がきっかけになりますか？ ライフサイクルはどうなっていますか？	「通知を送信する」— リアルタイム？ バッチ処理？ どのイベントがきっかけ？
Why（なぜ）	どんな問題を解決しますか？ 成功の基準は何ですか？	「パフォーマンスを向上させる」— レイテンシ？ スループット？ コスト？
How（どのように）	実装上の制約はありますか？	「既存の技術スタックを使う」— どの部分ですか？ 例外はありますか？

ステージ 2：曖昧さの評価

各観点の明確さを評価します。

• 明確 — 明示されているか、文脈から明確に読み取れる
• 想定可能 — 明示されていないが、妥当な既定値がある（既定値を示す）
• 曖昧 — 複数の妥当な解釈があり、誤った推測は作業の無駄につながる

曖昧な観点の数を数えます。

• 曖昧な観点が 0 個 → 進行可能。 すぐに進めます。「スコープは明確です。進めます。」と伝えます。
• 曖昧な観点が 1～2 個 → 簡潔に確認。 既定値を添えて、的を絞った質問を 1～2 つします。
• 曖昧な観点が 3 個以上 → 必ず確認。 影響の大きい質問を最大 3 つします。回答があるまで進めないでください。

ステージ 3：明確化の質問を作成

曖昧な観点ごとに（最大 3 つ、影響の大きい順に優先して）：

**Q[N]: [Specific question]**
Options: (a) [option] (b) [option] (c) [option]
My default: (b) — [why this is the reasonable default]
Impact: [what changes depending on the answer]

ステージ 4：確認して進行

回答を受け取った後（またはユーザーが「既定値で進めて」と伝えた後）：

1. 明確になったスコープを 3～5 個の箇条書きで言い直します
2. 残っている想定があれば記載します（曖昧ではなく、想定可能として評価）
3. 実行に進みます

出力形式

## Scope Analysis: [Request Summary]

### 5W1H Decomposition
| Dimension | Status | Detail |
|:----------|:-------|:-------|
| What | Clear / Assumable / Ambiguous | [extracted or missing info] |
| Who | Clear / Assumable / Ambiguous | [extracted or missing info] |
| Where | Clear / Assumable / Ambiguous | [extracted or missing info] |
| When | Clear / Assumable / Ambiguous | [extracted or missing info] |
| Why | Clear / Assumable / Ambiguous | [extracted or missing info] |
| How | Clear / Assumable / Ambiguous | [extracted or missing info] |

### Ambiguity Score: [N]/6 → [Green light / Quick clarify / Must clarify]

### Questions (if any)

**Q1: [Question]**
Options: (a) ... (b) ... (c) ...
My default: (b) — [reason]
Impact: [what changes]

**Q2: ...**

### Clarified Scope (after answers)
- [bullet 1]
- [bullet 2]
- [bullet 3]

### Remaining Assumptions
- [assumption 1] — rated Assumable because [reason]

品質の調整

悪いスコープの明確化（これは避ける）

User: "Build me an auth system"

AI: I have a few questions before we start:
1. What programming language would you like to use?
2. What database do you prefer?
3. Do you want tests?
4. What's your timeline?
5. How many users do you expect?
6. Should it be containerized?
7. What CI/CD platform do you use?

問題点：

• 質問が 7 つあり、多すぎます。そのほとんどは認証のスコープに影響しません
• 「言語は何ですか？」— プロジェクトを見れば明らかです
• 「テストは必要ですか？」— 常に必要です。スコープに関する質問ではありません
• 「期限はいつですか？」— 作るものは変わりません
• 選択肢がなく、既定値も示されていません
• 5W1H の構成ではなく、ただ思いついたことを並べています

GOOD スコープの明確化（これを実行）

User: "Build me an auth system"

## Scope Analysis: Auth System

### 5W1H Decomposition
| Dimension | Status | Detail |
|:----------|:-------|:-------|
| What | Ambiguous | "Auth system" — login only? signup? password reset? SSO? |
| Who | Ambiguous | User roles not specified — single role or RBAC? |
| Where | Clear | Next.js app (inferred from project structure) |
| When | Clear | Standard request-response auth flow |
| Why | Assumable | Secure user access (standard) |
| How | Assumable | Project uses TypeScript + Prisma (from codebase) |

### Ambiguity Score: 2/6 → Quick clarify

**Q1: What auth flows are needed?**
Options: (a) Email/password login only (b) Login + signup + password reset (c) Full OAuth2 with Google/GitHub providers
My default: (b) — most apps need the complete basic flow
Impact: (a) = 2 hours, (b) = 4 hours, (c) = 8 hours + provider setup

**Q2: User roles?**
Options: (a) Single role — all users equal (b) Admin + User (c) Custom RBAC with permissions
My default: (a) — add roles later when needed (YAGNI)
Impact: (c) requires permission tables, middleware, and role management UI

これがより優れている理由：

• 質問は2つだけで、どちらも影響の大きい内容です
• 選択肢が明確な複数選択式です
• デフォルトの選択肢とその理由が示されています
• 影響を定量化しています（時間、複雑さ）
• 4つの観点はすでに文脈から解決されており（無駄な質問はありません）
• 5W1Hの構成により、分析が明確になります

使用するタイミング

• 重要なタスクや機能リクエストを開始するとき
• リクエストに具体性のない「system」「module」「feature」「improve」「fix」などの言葉が含まれているとき
• ユーザーの希望について推測していることに気づいたとき
• 解釈によってタスクに2時間かかることも2週間かかることもあるとき
• 他のStack Skillを実行する前（まずスコープを明確にしてから、調査、レビュー、計画を行います）

使用しないタイミング

• 再現手順のあるバグ報告（スコープはそのバグです）
• 明確で詳細な仕様があるとき（「idとnameを返すGET /usersエンドポイントを追加する」など）
• 文脈が確立されている進行中の会話で、追加タスクを行うとき
• 簡単な質問（「この関数は何をしますか？」など）
• ユーザーが「とにかく実行して」または「判断は任せる」と明示しているとき

注意点

1. 読めば分かることは質問しないでください。 プロジェクトにpackage.json、tsconfig.json、または既存のコードがある場合は、「言語やフレームワークは何ですか？」と尋ねる前に確認してください。これは明確化ではなく、怠慢です。
2. 質問は最大3つまでです。これが絶対的な上限です。 それ以上必要な場合は、質問を増やすのではなく、リクエストをサブタスクに分解する必要があります。
3. スタイルの好みはスコープに関する質問ではありません。 命名規則、フォルダー構成、フォーマットには、プロジェクトの規約または妥当なデフォルトを使用してください。これらを理由に作業を止めないでください。
4. 質問ごとにデフォルトを明示してください。 ユーザーが「デフォルトで進めて」と言えば、すべての質問を省略できるようにします。デフォルトを明示していなければ、対応が不十分です。
5. 承認されたら、すぐに進めてください。 リクエストが明確なら、そう伝えてただちに作業に進んでください。十分に念入りに見せるためだけに質問してはいけません。

統合に関する注意

• 最初に行うこと： swing-clarifyは最初に実行するよう設計されています。明確になったスコープは、他のすべてのスキルに反映されます。
• swing-researchとの連携： 明確になったスコープ → 焦点を絞った調査の質問（誤った対象を調査するのを防ぎます）
• swing-reviewとの連携： 明確になったスコープ → 実際の要件に基づくレビュー（推測した要件に基づくレビューを防ぎます）
• swing-optionsとの連携： 明確になった制約 → より適切な選択肢の生成（制約によって、慣例的な方法と慣例にとらわれない方法が定まります）
• swing-mortemとの連携： 明確になった前提 → より具体的な失敗シナリオ
• swing-traceとの連携： 明確になったスコープ → Stage 1での主張の切り分けがより明確になります（追跡すべき曖昧な前提が減ります）