clarification

反復的な調査による明確化

曖昧なユーザーの依頼を、明確に定義された作業範囲へと絞り込みます。まずコードベースを調査し、そこで見つかった内容に基づいて質問を行い、曖昧さがなくなるまで繰り返します。

基本原則

曖昧さは一度のやり取りでは解消されません。調査と質問を何度も繰り返し、全体像を徐々に明確にします。まず調査を行います。コードベースを確認したエージェントなら、確信を持って具体的な質問ができます。確認していないエージェントは一般的な質問をして、ユーザーの回答を無駄にしてしまいます。このスキルの目的は「コードを書くこと」ではなく、「ユーザーが何を望んでいるか」と「コードベースがどのような状態にあるか」を明確にすることです。

必須のゲート

1. 質問する前に調査します。 最初の質問の前に、必ず調査サブエージェントを起動します。すべての質問は調査結果に基づいていなければなりません。コードベースを見れば分かることをユーザーに尋ねてはいけません。
2. 必ずサブエージェントを使います。 最初の質問の前にサブエージェントを起動し、ユーザーの回答を受けた後も再度起動します。
3. 「これで十分に明確です」と言えるようになるまで実装を始めません。 コードベースのレベルで、理解が完全になっている必要があります。
4. すべての質問で作業範囲を絞り込みます。 同じ曖昧さのレベルで質問を繰り返してはいけません。独立した質問は1回のラウンドにまとめてもかまいません（例：AskUserQuestionを使い、最大4つまで）。関連する質問は、段階的に尋ねます。ラウンド数を固定せず、曖昧さがなくなった時点でループを終了します。
5. コード調査の生の結果をユーザーにそのまま提示してはいけません。 ユーザーの質問に沿って、調査結果を要約します。

使用する場合

• ユーザーが「〜したい」と言っているものの、作業範囲が不明確な場合
• 依頼が曖昧で、実装に複数の方向性が考えられる場合
• ユーザー自身も、望んでいることを十分に言語化できていない場合
• 既存のコードベース構造と衝突するおそれがあり、調査が必要な場合

使用しない場合

• 依頼がすでに具体的で明確な場合（実装または計画のスキルに進みます）
• 簡単なバグ修正や設定変更など、作業範囲が明らかな場合
• ユーザーが「質問せずに、そのまま進めて」と明示している場合

プロセス：まず調査し、その後に質疑応答を繰り返す

フェーズ0：最初の調査（質問する前）

曖昧な依頼を受け取ったら、ユーザーに何か尋ねる前に、ただちにExploreサブエージェントを起動します。調査では、依頼が関係する可能性のある領域、すなわちファイル構成、既存のパターン、インターフェースの境界、最近の関連変更、テストの網羅状況を把握します。

調査の実行中に、依頼を分析して曖昧な点を洗い出します。最初の質問ラウンドを作成するのは、調査結果が返ってきた後です。そうすれば、コードの実際の状態に基づいて質問できます。「コードベースでは、すでにservices/y.tsでXに対応しています。このパターンに沿うべきでしょうか、それとも置き換えるべきでしょうか？」

トラック1：ユーザーとの質疑応答（曖昧さの解消）

曖昧さを解消するため、ユーザーに質問します。

質問の原則：

• すべての質問を調査結果に基づかせ、見つかった内容を示します
• 独立した質問は1回のラウンドにまとめ（最大4つ）、関連する質問は段階的に尋ねます
• 可能であれば、選択肢（A/B/C）を提示します
• 回答から新たな曖昧さが生じたら、次のラウンドで掘り下げます
• 抽象的な意図ではなく、具体的な状況を引き出すために、「なぜ？」ではなく「どのケースですか？」と尋ねます
• 回答が以前の回答と矛盾する場合は、すぐにその点を伝えて認識を合わせます

質問の順序の目安：

1. 目的：「この作業の最終的な目標は何ですか？」（達成したいこと）
2. 範囲：「何を含め、何を除外しますか？」（境界を明確にする）
3. 制約：「影響する既存の制約はありますか？」（時間、互換性、依存関係）
4. 成功基準：「完了時にどのような状態になっていればよいですか？」（検証可能な成果）
5. 優先順位：「複数の方法がある場合、最も重視するのは何ですか？」（トレードオフ）

質問の後は、その時点で明らかになっていることを簡潔にまとめます。

トラック 2：コードベースの調査（技術的なコンテキスト）

調査は最初の質問より前（フェーズ 0）に始まり、ラウンドの合間にも続きます。ユーザーの回答によって、新たに調査する価値のある領域が見つかることがよくあります。

調査の依頼方法：

回答（またはそれまでの調査結果）によって新しい領域が明らかになったら、すぐに追加のサブエージェントを起動します。通常は、次の質問ラウンドを提示した直後に起動し、ユーザーが回答している間に調査を進めます。サブエージェントは次の内容を調査します。

• 関連するファイル構成と命名規則
• 既存の実装パターン（エラー処理、状態管理、データフロー）
• 依存関係とインターフェースの境界
• 最近の変更履歴（関連するコミット）
• テストカバレッジの状況

サブエージェント向けプロンプトのテンプレート：

subagent_type: Explore
description: "Explore [topic] codebase"
prompt: |
  The user has requested [summarized request].

  Investigate and report on:
  1. Related files and the role of each
  2. Existing implementation patterns (is something similar already in place?)
  3. Boundary areas this work is likely to affect
  4. Recent related changes
  5. Existing test state

  Report only key findings concisely.
  Do not dump entire file contents.

サブエージェントの結果の処理：

サブエージェントから調査結果が返ってきたら：

1. ユーザーの回答と照らし合わせて相互検証します
2. ユーザーが把握していない技術的な制約が見つかった場合は、次の質問に反映します
3. 既存のコードと競合する可能性が高い場合は、ユーザーに知らせます

全体をつなぐ：ループ

digraph clarification {
    rankdir=TB;
    "User states vague request" [shape=box];
    "Dispatch recon subagents" [shape=box, style=dashed];
    "Assess ambiguities + receive recon findings" [shape=box];
    "Ask informed question round" [shape=box];
    "Dispatch follow-up exploration" [shape=box, style=dashed];
    "Receive user answers" [shape=box];
    "Synthesize: still ambiguous?" [shape=diamond];
    "Present context brief" [shape=doublecircle];

    "User states vague request" -> "Dispatch recon subagents";
    "Dispatch recon subagents" -> "Assess ambiguities + receive recon findings";
    "Assess ambiguities + receive recon findings" -> "Ask informed question round";
    "Ask informed question round" -> "Dispatch follow-up exploration" [style=dashed, label="parallel"];
    "Ask informed question round" -> "Receive user answers";
    "Dispatch follow-up exploration" -> "Synthesize: still ambiguous?" [style=dashed];
    "Receive user answers" -> "Synthesize: still ambiguous?";
    "Synthesize: still ambiguous?" -> "Ask informed question round" [label="yes"];
    "Synthesize: still ambiguous?" -> "Present context brief" [label="no"];
}

各サイクル：

1. ユーザーの回答を受け取ります
2. サブエージェントの結果があれば統合します（調査中の場合は、次のサイクルで統合します）
3. 「残っている曖昧な点」の一覧を更新します
4. 次の質問ラウンドを構成します（スコープへの影響が大きいものを優先し、互いに独立した質問だけをまとめます）
5. 必要に応じて追加のサブエージェントを起動します（回答や以前の調査によって新たに調査すべき領域が判明した場合）

出力：コンテキストブリーフ

曖昧な点が十分に解消されたら、ユーザーにコンテキストブリーフを提示します。これがこのスキルの最終成果物です。

コンテキストブリーフの形式：

## Context Brief: [Task Title]

### Goal
[One-sentence task goal]

### Scope
- **In scope**: [Included work]
- **Out of scope**: [Explicitly excluded work]

### Technical Context
[Technical facts discovered through code exploration]
- Current implementation state
- Affected areas
- Existing patterns to follow

### Constraints
[Identified constraints]
- External constraints
- Technical constraints
- Time/priority constraints

### Success Criteria
[Specific criteria for the completed state]

### Open Questions (if any)
[Questions still open — unresolved but not blocking]

### Complexity Assessment

Assess task complexity using these 5 signals. Score each signal, then determine the routing.

| Signal | Low (1) | Medium (2) | High (3) |
|--------|---------|-----------|----------|
| **Scope breadth** | Single feature or component | 2-3 related components | 4+ components or cross-cutting concerns |
| **File impact** | ≤3 files | 4-8 files | 9+ files or across 3+ directories |
| **Interface boundaries** | Works within existing interfaces | Extends existing interfaces | Defines new interfaces or modifies contracts |
| **Dependency depth** | No ordering constraints | Linear dependency chain | Branching dependencies requiring DAG |
| **Risk surface** | No integration risk | Internal integration between components | External systems, schema changes, backward compatibility |

**Score:** [sum of signals, range 5-15]
**Verdict:** [Simple (5-8) | Borderline (9) | Complex (10-15)]
**Rationale:** [1-2 sentences explaining the dominant complexity factor]

### Suggested Next Step
[Auto-determined by Complexity Assessment verdict — see Routing Rules below]

コンテキストブリーフをファイルに保存する：

docs/engineering-discipline/context/YYYY-MM-DD-<topic>-brief.md

（ユーザーが別の場所を指定した場合は、その場所に従います。）

まず会話内でコンテキストブリーフを提示し、ユーザーの承認を得てからファイルに保存します。このファイルは plan-crafting スキルへの入力として直接使用されます。

要注意の兆候

次のいずれかが発生した場合は、作業を止めて方針を見直します。

状況	対応
ユーザーが「とにかく判断して」と言う	曖昧な点を解消せずに着手すると、手戻りが発生する可能性が高いことを警告します。最低限、目的と成功基準を確認します
同じトピックについて 3 回以上質問している	ユーザー自身も本当に把握していません。既知の点と未知の点を切り分け、未知の点について前提を提示して確認します
サブエージェントが既存コードとの競合を発見した	直ちにユーザーに知らせます。既存の構成との競合には、設計上の判断が必要です
依頼が複数の独立したサブタスクに分かれる	分解した内容をユーザーに示し、1 つずつ優先して進めることを提案します

アンチパターン

アンチパターン	失敗する理由
調査結果が返る前に最初の質問をする	コードベースから分かる一般的な質問になり、ユーザーの時間と信頼を損ないます
依存関係のある質問を 1 回のラウンドにまとめる	同じバッチ内で後の回答によって先の回答が無効になることがあります
コードを調査せずに質問する	既存のコードと競合する方向にスコープが狭まる可能性があります
サブエージェントの出力をすべてユーザーに見せる	情報が多すぎます。ユーザーの状況に関係する要約だけを提示します
独断で「これで十分」と判断する	必ずコンテキストブリーフをユーザーに提示し、確認を得ます
実装を開始する	このスキルの終了点は「コンテキストが明確になった状態」であり、「コードの実装」ではありません

最小チェックリスト

各サイクルの最後に自己確認します。

• このサイクルで少なくとも 1 つの曖昧な点が解消されましたか？
• サブエージェントによる調査は進行中、または完了していますか？
• 次の質問ラウンドは、これまでの回答と調査結果の両方に基づいていますか？
• 進捗をユーザーに明確に伝えましたか？

ルーティングルール

Context Brief が承認された後、複雑度評価の判定によって次に使用するスキルが決まります。

判定	ルート	理由
Simple（スコア 5-8）	plan-crafting	1 回の計画サイクルで完了できるタスクです。直接計画を立てれば十分です。
Borderline（スコア 9）	ユーザーが決定	推奨案とともに両方の選択肢を提示します。
Complex（スコア 10-15）	milestone-planning	複数回の計画サイクルが必要なタスクです。計画の前にマイルストーンへ分解する必要があります。

例外： ユーザーはいつでもルートを変更できます。複雑なタスクに対してユーザーが「そのまま計画して」と指示した場合は、plan-crafting に進みます。単純なタスクに対して「マイルストーンに分解して」と指示した場合は、milestone-planning に進みます。

Borderline（スコア 9）： 推奨案とともに両方の選択肢をユーザーに提示します。例：「スコアは 9 で、境界線上です。［支配的な要因］のため、milestone-planning をおすすめしますが、［条件］であれば plan-crafting でも対応できます。どちらにしますか？」

Context Brief の「次のステップの提案」フィールドには、このルーティングを反映する必要があります。

• Simple（5-8）：「plan-crafting に進みます — タスクは 1 回の計画サイクルで完了できます。」
• Borderline（9）：「［支配的な要因］のため［ルート］をおすすめしますが、［条件］であれば［もう一方のルート］も実行可能です。ユーザーの選択が必要です。」
• Complex（10-15）：「milestone-planning に進みます — 複数フェーズで実行するために、マイルストーンへの分解が必要です。」

移行

Context Brief がユーザーに承認されたら、複雑度評価に基づいてルートを選択します。

• Simple（スコア 5-8）→ plan-crafting スキル — 1 サイクルでの実装計画
• Borderline（スコア 9）→ 推奨案とともに両方の選択肢を提示し、ユーザーが決定
• Complex（スコア 10-15）→ milestone-planning スキル — 複数フェーズのマイルストーン分解を行い、その後 long-run で実行
• さらに調査が必要な場合 → clarification スキル自体の Q&A ループを続行
• スコープがすでに些細で、計画が不要な場合 → 直接実装

このスキル自体が次のスキルを呼び出すことはありません。 Context Brief を提示してファイルに保存し、ルーティング先の次のステップを提案して終了します。

Context Brief → plan-crafting のマッピング：

Context Brief のフィールド	plan-crafting の入力
Goal	計画ヘッダーの「目標」
Scope (In/Out)	計画ヘッダーの「作業範囲」
Technical Context	「アーキテクチャ」＋「技術スタック」＋ファイル構造マッピングの基礎
Constraints	タスク分解時に制約を反映
Success Criteria	Self-Review の基準
Open Questions	計画に仮定（assumption）として反映し、ユーザーに確認