analyze-with-file

ファイルを使った分析

議論のプロセスを記録しながら、対話形式で共同分析を行います。理解の変化を記録し、複数ラウンドにわたる質疑応答を促進し、インライン検索と外部調査を活用して深く掘り下げます。

基本的な流れ：トピック → 調査 → 議論 → 洗練 → 結論 → 次のステップ

自動モード（-y）：調査に関する判断を自動確認し、推奨される観点を使用して、対話形式での範囲設定を省略します。

設定

フラグ	デフォルト	説明
-y, --yes	false	すべての判断を自動確認します
--continue	false	既存のセッションを続行します
--depth	standard	quick / standard / deep

セッション ID：ANL-{YYYY-MM-DD}-{slug}

• slug：topic.toLowerCase() → [a-z0-9\u4e00-\u9fa5] を維持し、それ以外を - に置換します。最大 40 文字です
• date：UTC+8 の YYYY-MM-DD
• 続行モードの自動検出：セッションフォルダーと discussion.md が存在する場合 → 続行モード

成果物

{projectRoot}/.workflow/.analysis/ANL-{date}-{slug}/
├── discussion.md              # Single source of truth: rounds, decisions, conclusions, synthesis
├── state.json                 # Session state: config, confidence, quality tracking
├── exploration-codebase.json  # Codebase exploration: files, patterns, constraints
├── research.json              # External research: best practices, pitfalls, sources
└── handoff.json               # Structured handoff (only on "执行任务")

ファイル	作成時期	目的
discussion.md	Phase 1	すべての分析内容：セッションのメタデータ、ラウンドごとの調査結果、多角的な統合、判断、意図の網羅状況、結論、推奨事項。上書きされるセクション：## Current Understanding。追記されるセクション：## Discussion Timeline。
state.json	Phase 0	機械可読データ：現在のラウンド、観点スコア、信頼度の履歴、品質の追跡情報（圧力チェック、チャレンジモード、停滞カウンター）、調査メタデータ。ラウンドごとに更新されます。
exploration-codebase.json	Phase 2	コードベースのコンテキスト：project_type、relevant_files[{path, relevance, summary, dimensions[]}]、patterns[{pattern, files, description}]、constraints[]、integration_points[{location, description}]、key_findings[]、_metadata{timestamp, exploration_scope}
research.json	Phase 2	外部調査：findings[{finding, detail, confidence, source_url}]、best_practices[{practice, rationale, source}]、alternatives[{option, pros, cons, verdict}]、pitfalls[{issue, mitigation, source}]、codebase_gaps[{gap, current_approach, recommended_approach}]、sources[{title, url, key_takeaway}]
handoff.json	Phase 4	「执行任务」の場合のみ：source、session_id、session_folder、summary、implementation_scope[{objective, rationale, priority, target_files[], acceptance_criteria[], change_summary}]、code_anchors[]、key_files[]、key_findings[]、decision_context[]、exploration_artifacts{exploration_codebase, research} — キーは workflow-lite-plan の artifactMapping と一致します

---

分析の流れ

Phase 0: Session Setup
   ├─ Parse topic, flags, generate session ID
   ├─ Detect project root (git rev-parse --show-toplevel || pwd)
   ├─ Create session folder (or detect existing → continue)
   ├─ Initialize state.json + discussion.md
   └─ functions.update_plan([phase-1..phase-4, next-step])

Phase 1: Topic Understanding
   ├─ Identify analysis dimensions from topic keywords
   ├─ Scope with user: focus, perspectives (1-4), depth
   ├─ Generate initial questions from dimensions
   └─ Write initial sections to discussion.md

Phase 2: Exploration
   ├─ Load project specs (ccw spec load)
   ├─ Codebase search → exploration-codebase.json
   ├─ External research via web.run → research.json
   ├─ Multi-perspective analysis → write to discussion.md
   ├─ Context budget gate (>30 files → rank + trim)
   ├─ Initial intent coverage check
   └─ Baseline confidence scoring → state.json

Phase 3: Interactive Discussion (max 5 rounds)
   ├─ Present findings + confidence + weakest dimension
   ├─ User direction: Deepen / Research / Adjust / Complete
   ├─ Cumulative context: always include prior findings
   ├─ Record-before-continue: write to discussion.md BEFORE state update
   ├─ Quality mechanisms:
   │   ├─ Pressure pass (mandatory ≥1 before Phase 4)
   │   ├─ Challenge injection (auto, round ≥2)
   │   ├─ Stall detection (2 consecutive no-progress rounds)
   │   └─ Re-score confidence → state.json
   ├─ Pre-synthesis readiness gate (on "Complete")
   ├─ Intent drift check (round ≥2)
   └─ Update discussion.md: append round + overwrite Current Understanding

Phase 4: Synthesis & Terminal Gate
   ├─ Intent Coverage Verification (mandatory gate)
   ├─ Findings → Recommendations Traceability (mandatory gate)
   ├─ Write synthesis + conclusions to discussion.md
   ├─ Recommendation review with user
   └─ Terminal gate: 执行任务 → handoff.json | 产出Issue | 完成

---

Phase 0：セッションの設定

1. トピックとフラグ（--depth、--continue、-y）について {{ARGUMENTS}} を解析します
2. プロジェクトのルートを検出します：git rev-parse --show-toplevel 2>/dev/null || pwd
3. セッション ID を生成します：ANL-{date}-{slug}、セッションフォルダー：{projectRoot}/.workflow/.analysis/{sessionId}
4. セッションフォルダーと discussion.md が存在する場合 → 続行モードに自動で入り、state.json を読み込んで最後のラウンドから再開します
5. セッションフォルダーを作成します：mkdir -p {sessionFolder}
6. state.json を初期化します：

{
  "session_id": "ANL-{date}-{slug}",
  "topic": "...",
  "depth": "standard",
  "dimensions": [],
  "perspectives": [],
  "focus_areas": [],
  "current_round": 0,
  "current_phase": "setup",
  "confidence": {
    "dimensions": {},
    "overall": 0,
    "weakest": null,
    "history": []
  },
  "quality": {
    "pressure_pass_done": false,
    "challenge_modes_used": [],
    "stall_counter": 0,
    "last_findings_count": 0,
    "readiness_gate_passed": false,
    "residual_risks": []
  }
}

7. 進捗の追跡を初期化します：

functions.update_plan([
  { id: "phase-1", title: "Phase 1: Topic Understanding", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Exploration & Research", status: "pending" },
  { id: "phase-3", title: "Phase 3: Interactive Discussion", status: "pending" },
  { id: "phase-4", title: "Phase 4: Synthesis & Conclusion", status: "pending" },
  { id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" }
])

---

Phase 1：トピックの理解

1.1 観点の特定

トピックのキーワードを分析の観点と照合します。複数の観点に一致する場合は、すべて含めます。一致するものがない場合は、デフォルトで「architecture」+「implementation」を使用します。

1.2 初期スコープ設定（新規セッション、自動モードではない場合）

最大 3 つの質問を含む functions.request_user_input の呼び出しを 1 回実行します（制約：質問は 1～4 個、各質問の選択肢は 2～4 個）。

質問 1 — 注目する領域（multiSelect: true）：

• Dimension-Direction Mapping を使用して、一致するディメンションから選択肢を動的に生成します。選択肢は最大 4 個です。

質問 2 — 視点（multiSelect: true）：

• 技術：実装パターン、コード構造、実現可能性
• アーキテクチャ：システム設計、スケーラビリティ、相互作用
• セキュリティ：セキュリティパターン、脆弱性、アクセス制御
• パフォーマンス：ボトルネック、最適化、リソース使用率

視点は最大 4 つです。デフォルトでは、視点を 1 つ選択します。

質問 3 — 深さ（multiSelect: false）：

• 標準（推奨）：網羅性を確保したバランスのよい分析
• クイック概要：表面的な内容をすばやく把握
• 詳細な調査：複数回にわたる包括的な調査

1.3 discussion.md の初期化

初期テンプレート全体を記述します（discussion.md Structure を参照）。

• ヘッダー：セッション ID、トピック、タイムスタンプ（UTC+8）、ディメンション、深さ
• 目次（各ラウンドで自動更新）
• 現在の理解：「調査後に入力」
• 分析コンテキスト：注目する領域、視点、深さ
• 初期の質問：トピックとディメンションから生成（分析で答えるべき重要な質問）
• 初期の決定：これらのディメンション／注目する領域を選んだ理由、除外した項目とその理由を記録
• 議論のタイムライン：空欄。後でラウンドを追加
• 決定の経緯：空欄。フェーズ 4 で入力

state.json を更新し、dimensions、perspectives、focus_areas、depth を設定します。phase-1 を completed、phase-2 を in_progress にします。

---

フェーズ 2：調査

調査はすべてインラインで行います。エージェントへの委任はありません。

2.1 コードベースの検出と仕様の読み込み

プロジェクトの種類を検出します。

• package.json → nodejs | go.mod → golang | Cargo.toml → rust | pyproject.toml → python | pom.xml → java | src/ が存在 → generic | それ以外 → none

コードベースが検出された場合は、プロジェクトのメタデータを読み込みます。

• functions.exec_command('ccw spec load --category exploration')
• functions.exec_command('ccw spec load --category debug')
• .workflow/specs/*.md を読み込み、プロジェクトの規約を確認します。

2.2 コードベースの検索

次のツールを使用して検索します：Grep、Glob、Read、mcp__ace-tool__search_context

注目する項目：トピックに関連するモジュール／コンポーネント、コードのパターン／構造、統合ポイント、設定／依存関係。

完全なスキーマで調査結果を exploration-codebase.json に記述します。

• project_type：検出された種類
• relevant_files[]：{path, relevance, summary, dimensions[]}
• patterns[]：{pattern, files, description}
• constraints[]：見つかったアーキテクチャ上の制約
• integration_points[]：{location, description}
• key_findings[]：コード検索から得られた主な知見
• _metadata：{timestamp, exploration_scope}

2.3 外部調査

実行条件：ディメンションに architecture|comparison|decision|performance|security が含まれる、またはトピックが best practice|pattern|vs|compare|approach|standard|library|framework に一致する場合。

純粋に内部のコードベースに関する質問（例：「モジュール X の仕組み」）ではスキップします。

web.run のクエリを最大 3 件実行します。

• {topic} best practices {year}
• {topic} common pitfalls and known issues
• 一致するディメンションごとに：{topic} {dimension} patterns and recommendations

完全なスキーマで調査結果を research.json に記述します。

• findings[]：{finding, detail, confidence, source_url}
• best_practices[]：{practice, rationale, source}
• alternatives[]：{option, pros, cons, verdict}
• pitfalls[]：{issue, mitigation, source}
• codebase_gaps[]：{gap, current_approach, recommended_approach}
• sources[]：{title, url, key_takeaway}
• _metadata：{queries_executed, timestamp}

相互参照を行い、コードベースのパターンが調査結果のベストプラクティスと異なる箇所を codebase_gaps として記録します。

2.4 多視点分析

単一視点（デフォルト）：探索と調査コンテキストを活用し、あらゆる側面を包括的に分析します。調査結果を discussion.md の Round 1 に直接記述します。

複数視点（2～4 視点、順次実施）：各視点を順番に分析します。各視点について、discussion.md の Round 1 に要約のサブセクションを記述します。その後、次の統合サブセクションを追加します。

• 共通するテーマ：すべての視点が合意している内容
• 相反する見解：視点によって異なる点
• 独自の貢献：特定の視点に固有の洞察

2.5 コンテキスト予算ゲート

探索の結果、exploration-codebase.json に関連ファイルが 30 個を超えている場合：

• 関連性スコア順に並べ、各次元の上位 30 個を残します
• exploration-codebase.json のリストを絞り込み、_budget{original_count, summarized_count} を更新します
• discussion.md に「探索发现 N 个相关文件，已精简至 30 个高相关文件」と記録します

2.6 Round 1 を discussion.md に記述

Round Template を使って、Discussion Timeline に追記します。

• 分析したソース、主要な調査結果と根拠の参照（ファイル:行）
• 外部調査の結果、ベストプラクティス、コードベースの不足点
• 複数視点の統合（該当する場合）
• 議論のポイントと未解決の質問
• Decision Log：特定の検索戦略や視点を選んだ理由

2.7 初期の意図カバレッジ確認

discussion.md のヘッダーからユーザーの当初の意図を抽出します。Round 1 の調査結果に照らして、それぞれを確認します。

• ✅ 対応済み
• 🔄 進行中
• ❌ 未検討

discussion.md に次の文を追記します。「接下来的讨论将重点关注未覆盖 (❌) 和进行中 (🔄) 的意图。」

2.8 ベースライン信頼度スコアリング

各次元を、重み付きの 5 つの要素で評価します（各要素は [0.0, 1.0]）。

要素	重み	評価内容
findings_depth	0.30	調査結果の深さ
evidence_strength	0.25	推論に対する確かな証拠の強さ
coverage_breadth	0.20	その次元をどの程度網羅しているか
user_validation	0.15	ユーザーが調査結果を確認したか（初期値は 0、フェーズ 3 で増加）
consistency	0.10	調査結果に矛盾がないか

全体の信頼度 = 各次元の重み付き平均。最も弱い次元を特定します。

state.json の confidence セクションを更新します。discussion.md に次の信頼度テーブルを追記します。

#### Confidence Score (Baseline)
| Dimension | Depth | Evidence | Coverage | Validation | Consistency | **Score** |
|-----------|-------|----------|----------|------------|-------------|-----------|
| {dim}     | {x}   | {x}     | {x}      | 0.00       | {x}         | **{x}**   |

Overall: {N}% | Weakest: {dim} ({N}%)
> < 60%: 建议继续深入 | 60-80%: 可选深入或收敛 | > 80%: 建议收敛到结论

フェーズ 2 の終了条件：exploration-codebase.json を作成済み（コードベースがある場合）、research.json を作成済み（トピックに応じて）、discussion.md を Round 1 で更新済み、初期の意図カバレッジ確認を完了済み、ベースライン信頼度を算出済み。

phase-2 を completed、phase-3 を in_progress にします。

---

フェーズ 3：対話型ディスカッション

最大 5 ラウンドです。各ラウンドで次の手順を実行します。

累積コンテキストのルール

既知の情報を再発見することを避けるため、フェーズ 3 のすべての分析アクションには、これまでの調査結果すべての要約を必ず含めます。

## KNOWN FINDINGS (DO NOT re-discover)
- Established files: {list from exploration-codebase.json}
- Key findings: {from discussion.md rounds}
- Open questions: {remaining}
## NEW TASK: Focus ONLY on unexplored areas below.

3.1 調査結果を提示し、方向性を確認

Round ≥ 2 の前置き：確立された合意事項、直前のラウンドの方向性、信頼度の変化を 1～2 文で要約します。例：「到目前为止，我们已确认 [facts]。上一轮 [direction]。Confidence 从 52% 提升到 67%，security 维度仍需深入。」

state.json から最新の信頼度を読み込みます。最も弱い次元を特定します。

functions.request_user_input で提示します（質問は 1 つ、multiSelect: false、選択肢は 4 つ）。

• さらに深掘りする：{weakest_dimension} (Recommended) — 信頼度が最も低い次元を深掘りします
• 外部調査 — 特定の技術やパターンについて web.run を実行します
• 方向性を調整 — 別の焦点や具体的な質問に切り替えます
• 分析を完了 — 統合に進みます（レディネスゲートを起動）

質問ヘッダーには次のように表示されます：Round {N} | Confidence: {N}% | 最弱: {dim} ({N}%)

3.2 プロセスの応答

記録してから続行するルール：以下の各パスでは、状態の更新や次のラウンドに進む前に、調査結果と議論の統合内容を必ず discussion.md に記録します。

記録チェックポイント（すべてのパス）：ユーザーの元の選択、方向性への影響、方向性が変わった場合は完全な Decision Record を記録します。

技術的な解決策のトリガー：具体的なファイルやパターンを含む実装方法が説明された場合、2 つ以上の選択肢が比較された場合、またはユーザーが方法を承認または却下した場合は、Technical Solution format を使用して記録します。

曖昧さの確認：「Proposed」ステータスの各 Technical Solution について、未解決の選択肢が残っていないことを確認します。選択肢が 2 つ以上あり、選択されたものがない場合は、次のようにフラグを立てます。

> **⚠️ Ambiguity**: [Solution] has [N] unresolved alternatives: [list]
> - **Needs**: [Decision criteria or exploration to resolve]

次のフィードバックラウンドでユーザーに提示します。

さらに詳しく調査

functions.request_user_input を使用してサブ質問を尋ねます（multiSelect: false、最大 4 つ）：

• 未解決の質問、確信度の低い調査結果、未調査の側面から、状況に応じた選択肢を最大 3 つ生成します
• ヒューリスティックな選択肢を 1 つ：「別の角度から検討」— ベストプラクティス、異なる視点、よりシンプルな代替案と比較します
• 「Other」は、ユーザーが指定する独自の方向性として自動的に提供されます

Grep/Glob/Read/mcp__ace-tool__search_context を使用してインライン検索を実行します。新しい調査結果を以前のコンテキストと統合します。確認済みの前提と調査の観点を記録します。

外部調査

調査トピックを尋ねます（選択肢は最大 4 つ）：

• 未解決の技術的な質問、検証されていないパターンから提案を最大 3 つ提示します
• カスタム選択肢を 1 つ：「カスタム」（Other 経由）

web.run({search_query: "{topic} best practices {year}"}) を実行します。調査結果を research.json に統合します（上書きではなく追記）。discussion.md に「Key Findings」として記録します。コードベースと照合し、新しい codebase_gaps にフラグを立てます。

方向性の調整

新しい焦点を尋ねます。調整後の視点から分析します。新しい洞察を以前の分析と比較します。トリガー、以前から新しい方向性への変化、予想される影響を Decision として記録します。

分析完了

Pre-Synthesis Readiness Gate を実行します。通過した場合はフェーズ 4 に進みます。ブロックされた場合は、ユーザーがギャップに対処するか、リスクを受け入れるかを選択します（残余リスクは state.json と discussion.md に記録します）。

このラウンドで分析を終了する理由を記録します。

3.3 ラウンドの記録

Round Template を使用して、議論のタイムラインに追記します：User Input、Decision Log、Key Findings、Technical Solutions、Analysis Results、Corrected Assumptions、Open Items、Confidence Score、Narrative Synthesis。

Consolidation Rules に従い、## Current Understanding を最新の統合状態で上書きします（追記ではありません）。

新しい Round N のリンクを使って ## Table of Contents を更新します。

3.4 品質管理の仕組み

各ラウンドの記録後に実行します。

圧力テスト（必須。フェーズ 4 の前に少なくとも 1 回）

quality.pressure_pass_done が false で、現在のラウンドに重要な調査結果がある場合：

確信度が最も高い調査結果を選び、圧力テストの段階に沿って順番に適用します：

1. 証拠の要求：「これを裏付ける具体的な証拠は何ですか？反例はありますか？」
2. 前提の検証：「これを真とする隠れた前提は何ですか？どのような依存関係が前提になっていますか？」
3. 境界とトレードオフ：「これを受け入れる場合、何を諦めるか、または明示的に除外する必要がありますか？」
4. 根本原因の確認：「これは根本原因ですか、それともさらに深い問題の兆候ですか？」

検証または修正されるまで、同じ調査結果の検討を続けます。網羅性を高めるために対象を切り替えてはいけません。検証を通過した調査結果は確信度の高いものに昇格させ、通過しなかったものにはフラグを立てます。

discussion.md に次のように記録します：

#### Pressure Pass (Round N)
> **Target**: [finding]
> - **Confidence claimed**: [level] | **Evidence**: [assessment]
> - **Hidden assumption**: [identified]
> - **Boundary impact**: [tradeoff or scope consequence]
> - **Verdict**: [Confirmed with evidence / Weakened — needs more data / Corrected]

state.json で quality.pressure_pass_done = true に設定します。

チャレンジモードの注入（自動、ラウンド ≥ 2）

各モードはセッションごとに最大1回実行されます。quality.challenge_modes_used[] で追跡します。

モード	トリガー	チャレンジ
Devil's Advocate	ラウンド 2 以降 AND いずれかの次元の信頼度 > 0.7	「[finding] が成立しない場合、分析結果はどのように変わりますか？ それを覆す可能性のある証拠はありますか？」
Scope Minimizer	重要な発見の数 > 5 AND スコープが拡大中（新しい次元が追加されている）	「統合できる発見はどれですか？ 実行可能な最小限の結論セットは何ですか？ 不必要な点を分析していませんか？」
Root Cause Probe	ユーザーのフィードバックに因果関係を示す表現（「なぜなら」「引き起こす」「によって」）が含まれる	「これは根本原因ですか、それとも症状ですか？ 上流で作用している要因はほかにありますか？」

discussion.md に記録します：

#### Challenge: {Mode}
> **Target**: [finding or observation]
> **Counter-scenario / Question**: [challenge content]
> **Result**: [survived / weakened / corrected]

停滞の検出

各ラウンドの後に、新しい発見があったか、前提が修正されたか、信頼度の変化が 5% を超えたかを評価します。

これらが2ラウンド連続でいずれもない場合（quality.stall_counter >= 2）：

• 未使用の場合、Root Cause Probe を自動注入します
• functions.request_user_input を通じてユーザーに次の3つの選択肢を提示します：
  • 視点を変える（推奨）：最も弱い次元、または未調査の次元に切り替える
  • 外部調査：外部のベストプラクティスを用いて行き詰まりを解消する
  • 結論をまとめる：現在の発見で十分なため、統合に進む
• 停滞カウンターをリセットします

信頼度の再採点

すべての次元のスコアを再計算します。ユーザーがラウンドを重ねて発見を確認するにつれて、user_validation 要素の値が上がります。

state.json を更新します：confidence.dimensions、confidence.overall、confidence.weakest。confidence.history[{round, overall, dimensions}] に追記します。

discussion.md に追記します：

#### Confidence Score (Round N)
Overall: {N}% ({+/-N}%) | Weakest: {dim} ({N}%)

3.5 統合前の準備状況ゲート

ユーザーが「分析完了」を選択したときにトリガーされます。次のいずれかに該当する場合は終了をブロックします：

1. ❌ 最新のカバレッジチェックに未対応の項目がある
2. 明示的に先送りされていない次元の信頼度が 40% 未満
3. quality.pressure_pass_done が false
4. 未解決の技術ソリューションの曖昧さがある（ステータスが Proposed で、代替案が2つ以上）

未解決の項目がある場合は、functions.request_user_input を通じて次の2つの選択肢を提示します：

• 補足して完了（推奨）：フェーズ 3 を続け、未解決の項目に対応する
• リスクを受け入れて続行：残存リスクを state.json の quality.residual_risks[] と discussion.md に記録し、フェーズ 4 に進む

3.6 意図のずれの確認（ラウンド ≥ 2）

discussion.md のヘッダーから元の意図を読み直します。フェーズ 2 のベースラインと比較します：

• ✅ ラウンド N で対応済み
• 🔄 対応中、現在の焦点
• ⚠️ X に暗黙的に取り込まれている — 明示的な確認が必要（取り込み済み ≠ 対応済み）
• ❌ 未検討

⚠️ または ❌ がある場合は、次のように積極的に提示します：「以下の元の意図がまだ十分にカバーされていません：[list]。優先順位を調整しますか？」

フェーズ 3 の終了条件：プレッシャーテストを1回以上実施し、各ラウンドで信頼度を採点し、準備状況ゲートを通過（またはリスクを受け入れ）し、トリガーを満たしたチャレンジモードを実行し、必要に応じて停滞検出による介入を行い、discussion.md を完全に更新します。

フェーズ 3 を完了としてマークし、フェーズ 4 を in_progress にします。

---

フェーズ 4：統合と最終ゲート

4.1 意図のカバレッジ検証（必須ゲート）

意図のカバレッジマトリックスを discussion.md に記述します：

### Intent Coverage Matrix
| # | Original Intent | Status | Where Addressed | Notes |
|---|----------------|--------|-----------------|-------|
| 1 | [text] | ✅ Addressed | Round N, Rec #M | |
| 2 | [text] | 🔀 Transformed | Round N → M | Original: X → Final: Y |
| 3 | [text] | ⚠️ Absorbed | Round N | Covered by Rec #M |
| 4 | [text] | ❌ Missed | — | Reason |

ゲート：❌ の項目は、(a) 追加のラウンドで対応するか、(b) ユーザーの確認を得て明示的に先送りする必要があります。

4.2 発見事項から推奨事項への追跡可能性（必須ゲート）

すべてのラウンドから、実行可能な発見事項をすべて収集します。情報源：実行可能な示唆を含む重要な発見、技術ソリューション（提案済み／検証済み）、特定されたギャップ、修正によって対処が示唆される前提。

それぞれに処置を割り当てます：

処置	意味
recommendation	番号付きの推奨事項に変換
absorbed	別の推奨事項に含める（どれに含めたかを指定）
deferred	理由を示してスコープ外とする
informational	実行可能な対応を必要としない、純粋な知見

ゲート：すべての発見事項に処置を割り当てる必要があります。null は認められません。

discussion.md に記述します：

### Findings Coverage Matrix
| # | Finding (Round) | Disposition | Target |
|---|----------------|-------------|--------|
| 1 | [finding] (R1) | recommendation | Rec #1 |
| 2 | [finding] (R2) | absorbed | → Rec #1 |
| 3 | [finding] (R3) | deferred | Low priority, future work |
| 4 | [finding] (R1) | informational | — |

4.3 Synthesis を discussion.md に書き込む

以下のセクションを追記します。

Synthesis & Conclusions：

• エグゼクティブサマリー
• 主な結論：{point, evidence, confidence: high|medium|low}
• 推奨事項（優先度の高い順）：それぞれに action（命令形の動詞＋対象）、rationale、priority、evidence_refs（file:line）、steps[{description, target, verification}] を含めます
• 未解決の質問
• フォローアップの提案：{type: issue|task|research, summary}

Current Understanding (Final) — 以下の内容で上書きします：

• 確認できたこと：確認済みのポイント、検証済みの調査結果
• 明確になったこと：重要な誤り → 正しい内容の訂正
• 主な洞察：今後の参考となる有益な学び

Decision Trail：

• 結果を左右した重要な決定
• 理由と時系列を含む方針の変更
• 行ったトレードオフとその理由

Session Statistics：ラウンドの合計数、主な調査結果の件数、対象とした側面、生成した成果物、決定の数、最終的な信頼度スコア、品質シグナルの概要（圧力パス、使用したチャレンジモード、停滞イベント）。

state.json を最終的な信頼度と品質シグナルで更新します。

4.4 推奨事項のレビュー（自動モードではスキップ）

functions.request_user_input を使ってまとめて提示します。1 回の呼び出しにつき最大 4 件の質問を、優先度の高い順に並べます。

推奨事項ごとに、次の 3 つの選択肢を提示します。

• 確認（推奨）：そのまま受け入れる → ステータスを "accepted" にする
• 修正：範囲や手順を調整する → 詳細を確認する → ステータスを "modified" にする
• 削除：不要として削除する → ステータスを "rejected" にする

すべてのレビュー決定を discussion.md と state.json に記録します。

Review Summary を追記します。

### Recommendation Review Summary
| # | Action | Priority | Steps | Status | Notes |
|---|--------|----------|-------|--------|-------|
| 1 | [action] | high | 3 | ✅ Accepted | |
| 2 | [action] | medium | 2 | ✏️ Modified | [notes] |
| 3 | [action] | low | 1 | ❌ Rejected | [reason] |

4.5 最終ゲート（必須）

このステップを完了しない限り、ワークフローは未完了です。

フェーズ 4 を completed にし、next-step を in_progress にします。

functions.request_user_input（3 つの選択肢）：

• タスクを実行（推奨）：実装範囲を作成し、計画作成に引き継ぐ
• Issue を作成：推奨事項を追跡可能な Issue に変換する
• 完了：成果物のパスを表示して終了する

タスクを実行

Step A — 範囲を作成：ステータスが "accepted" または "modified" の推奨事項を抽出します。優先度順に並べ替えます。それぞれについて、{objective, rationale, priority, target_files[], acceptance_criteria[], change_summary} を作成します。

Step B — ユーザーによる範囲の確認（自動モードではスキップ）：範囲の概要を提示し、functions.request_user_input（3 つの選択肢）を呼び出します。

• 実行を確認（推奨）：引き継ぎに進む
• 範囲を調整：範囲を縮小または拡大する → 再確認する
• 基準を追加：受け入れ基準を追加または調整する → 再確認する

Step C — handoff.json を書き込む（workflow-lite-plan の成果物ブリッジと整合するスキーマ）：

{
  "source": "analyze-with-file",
  "session_id": "...",
  "session_folder": "...",
  "summary": "...",
  "implementation_scope": [
    { "objective": "...", "rationale": "...", "priority": "high|medium|low",
      "target_files": [], "acceptance_criteria": [], "change_summary": "..." }
  ],
  "code_anchors": [],
  "key_files": [],
  "key_findings": [],
  "decision_context": [],
  "exploration_artifacts": {
    "exploration_codebase": "{sessionFolder}/exploration-codebase.json",
    "research": "{sessionFolder}/research.json"
  }
}

Codex バージョンでは explorations.json/perspectives.json は別途作成されません（すべて discussion.md に記録されます）。ファイルに保存される成果物は exploration_codebase と research のみです。

Step D — 計画チェックリストを discussion.md に追記する：

## Plan Checklist
> **This is a plan only — no code was modified.**
- **Recommendations**: {count}
- **Generated**: {timestamp}

### 1. {objective}
- **Priority**: {level}
- **Rationale**: {reason}
- **Target files**: {list or TBD}
- **Acceptance criteria**: {list}
- [ ] Ready for execution

Issue を作成

受け入れた推奨事項ごとに、次の内容で ccw issue create を実行します。

• title：推奨事項のアクション
• context：アクション＋理由＋根拠の参照
• priority：high→2、medium/low→3
• source："discovery"
• labels：分析の側面

作成された Issue ID と次のステップのヒントを表示します。

完了

成果物のパスを表示して終了します。

next-step を completed にします。全工程を通じてソースコードは変更されません。

---

記録プロトコル

記録のトリガールール

次の事象が発生したら、直ちに discussion.md に記録します。

トリガー	対象セクション
方針の選択／範囲の調整	#### Decision Log
重要な調査結果の発見	#### Key Findings
前提の訂正	#### Corrected Assumptions
ユーザーからのフィードバック	#### User Input
意見の相違またはトレードオフ	#### Decision Log
技術的解決策の提案／検証／却下	#### Technical Solutions
圧力パスの実行	#### Pressure Pass
チャレンジモードの実行	#### Challenge

記録形式

決定：

> **Decision**: [description]
> - **Context**: [trigger]
> - **Options considered**: [alternatives]
> - **Chosen**: [approach] — **Reason**: [rationale]
> - **Rejected**: [why others discarded]
> - **Impact**: [effect on direction/conclusions]

調査結果：

> **Finding**: [content]
> - **Confidence**: [High/Medium/Low] — **Why**: [evidence basis]
> - **Hypothesis Impact**: [Confirms/Refutes/Modifies] hypothesis "[name]"
> - **Scope**: [affected areas]

技術的解決策（記録するタイミング：具体的なファイルやパターンを用いた実装方針が示されたとき、2つ以上の代替案を比較したとき、ユーザーが確認・修正・却下したとき、具体的なコード変更戦略が明らかになったとき）：

> **Solution**: [approach/pattern/implementation]
> - **Status**: [Proposed / Validated / Rejected]
> - **Problem**: [what it solves]
> - **Rationale**: [why this approach]
> - **Alternatives**: [other options, why not chosen]
> - **Evidence**: [file:line refs]
> - **Next Action**: [follow-up or none]

ナラティブの統合（各ラウンド後に追記）：

### Round N: Narrative Synthesis
**起点**: 基于上一轮的 [conclusions/questions]，本轮从 [starting point] 切入。
**关键进展**: [findings] [confirmed/refuted/modified] 了关于 [hypothesis] 的理解。
**决策影响**: 用户选择 [feedback type]，分析方向 [adjusted/deepened/maintained]。
**当前理解**: 核心认知更新为 [updated understanding]。
**遗留问题**: [remaining questions]

原則

• 即時性：フェーズの最後ではなく、決定が行われた時点で記録します
• 網羅性：背景、選択肢、選択したもの、その理由、却下したもの、影響を記録します
• 追跡可能性：後続フェーズから、あらゆる決定の経緯をたどれるようにします
• 深さ：結果だけでなく、推論や仮説が及ぼす影響も記録します

---

discussion.md の構造

# Analysis Discussion

**Session**: {id} | **Topic**: {topic} | **Started**: {timestamp}
**Dimensions**: {list} | **Depth**: {level}

## Table of Contents


## Current Understanding

### What We Established
### What Was Clarified
### Key Insights

## Analysis Context
- Focus areas: {list}
- Perspectives: {list}
- Depth: {level}

## Initial Questions
- {generated from topic + dimensions}

## Initial Decisions
> Record WHY these dimensions/focus areas were selected, what was excluded and why.

---
## Discussion Timeline

### Round 1 - Exploration ({timestamp})
#### Key Findings
#### Decision Log
#### Technical Solutions
#### Analysis Results
#### External Research
#### Multi-Perspective Synthesis
#### Intent Coverage Check
#### Confidence Score (Baseline)
#### Narrative Synthesis

### Round N - [Deepen|Research|Adjust] ({timestamp})
#### User Input
#### Decision Log
#### Key Findings
#### Pressure Pass
#### Challenge
#### Technical Solutions
#### Analysis Results
#### Corrected Assumptions
#### Open Items
#### Confidence Score (Round N)
#### Intent Coverage Check
#### Narrative Synthesis

---
## Synthesis & Conclusions
### Intent Coverage Matrix
### Findings Coverage Matrix
### Executive Summary
### Key Conclusions
### Recommendations
### Recommendation Review Summary
### Open Questions

## Decision Trail

## Plan Checklist (if 执行任务)

## Session Statistics

統合ルール

## 現在の理解 を上書きする際は、次のルールに従います。

ルール	説明
確認済みの知見を昇格させる	検証済みの調査結果を「確立したこと」に移します
修正内容を追跡する	重要な 誤り → 正しい内容 の変化を残します
現状に焦点を当てる	これまでの経緯ではなく、現在わかっていることを記載します
時系列の繰り返しを避ける	議論の詳細を統合したセクションにコピーしません
重要な学びを維持する	今後も役立つ知見を残します

悪い例：「第1ラウンドでは X を議論し、第2ラウンドでユーザーが Y と述べました……」 良い例：現在の事実のみを記載した、構造化されたサブセクション（確立したこと／明確化したこと／重要な知見）。

---

参考情報

分析の観点

観点	キーワード
アーキテクチャ	アーキテクチャ、architecture、設計、design、構造、structure、パターン
実装	実装、implement、コード、coding、ロジック
パフォーマンス	パフォーマンス、performance、最適化、optimize、ボトルネック、speed
セキュリティ	セキュリティ、security、認証、auth、権限、permission、脆弱性
概念	概念、concept、理論、theory、原則、principle、原理、理解
比較	比較、compare、違い、difference、versus
決定	決定、decision、選択、choice、トレードオフ、tradeoff

分析の視点

視点	焦点	最適な用途
技術	実装パターン、コード構造、実現可能性	方法や技術的な詳細
アーキテクチャ	システム設計、スケーラビリティ、コンポーネント間の相互作用	構造と構成
セキュリティ	セキュリティパターン、脆弱性、アクセス制御	セキュリティリスク
パフォーマンス	ボトルネック、最適化、リソース利用	パフォーマンスの問題

深さのレベル

深さ	範囲
クイック	表面的な確認、最小限の調査
標準	バランスの取れた分析と十分な網羅性（デフォルト）
詳細	複数ラウンドにわたる包括的な調査

観点と方向性の対応付け

一致した観点から、動的に焦点の選択肢を生成します。

観点	可能な方向性
アーキテクチャ	システム設計、コンポーネント間の相互作用、技術の選択、統合ポイント、設計パターン、スケーラビリティ戦略
実装	コード構造、実装の詳細、コードパターン、エラー処理、テスト方針、アルゴリズム分析
パフォーマンス	パフォーマンスのボトルネック、最適化の機会、リソース利用、キャッシュ戦略、並行処理の問題
セキュリティ	セキュリティの脆弱性、認証／認可、アクセス制御、データ保護、入力検証
概念	概念的な基盤、コアメカニズム、基本パターン、理論と原則、トレードオフと推論
比較	ソリューションの比較、長所と短所の分析、技術の評価、アプローチの違い
決定	決定基準、トレードオフ分析、リスク評価、影響分析、実装への影響

一致した観点ごとに上位2～3個の方向性を提示し、複数選択とカスタム方向性の指定を可能にします。

---

エラー処理

状況	対応	復旧方法
コードベースが検出されない	トピックのみを分析	コードベースの検索をスキップ
コードベースの検索に失敗	利用可能なコンテキストで続行	制限事項をdiscussion.mdに記録
関連する調査結果がない	キーワードを広げる	ユーザーに説明を求める
ユーザーのタイムアウト	状態を保存	--continue で再開
最大ラウンド数に到達（5）	強制的に統合	未解決の質問を明示
セッションフォルダーが競合	タイムスタンプのサフィックスを追加	一意のフォルダーを作成
推奨事項が生成されない	計画を生成しない	ユーザーに伝え、代替案を提案
ウェブ調査に失敗	コードベースのみを分析	制限事項を記録し、codebase_gapsとしてフラグを付ける
調査結果とコードベースが矛盾	codebase_gapsとしてフラグを付ける	相違点をユーザーの確認用に提示
分析が停滞（2ラウンド以上）	課題を自動で提示	ユーザー：視点の変更／調査／収束
準備状況ゲートにより終了がブロック	ギャップの概要を表示	ユーザーがギャップに対処するか、リスクを受け入れる
コンテキストの予算を超過	上位30件に順位付けして絞り込む	discussion.mdに記録

---

使用する場面

このスキルを使用する場合：複雑なトピックの探索、複数ラウンドにわたる理解の精緻化、複数の視点を踏まえた意思決定、実装前の共通認識の構築、外部調査を含む分析の経緯を記録する必要がある場合。

代替案を検討する場合：

• バグの診断 → debug-with-file
• アイデアの創出 → brainstorm-with-file
• 実装の準備が整っている場合 → lite-plan

---

次のトピックについて、analyze-with-fileワークフローを実行してください：$TOPIC