claude-code-workflow 7.2.11 → 7.2.13

package/.claude/agents/workflow-research-agent.md

@@ -0,0 +1,112 @@
+---
+name: workflow-research-agent
+description: External research agent — web search for API details, design patterns, best practices, and technology validation. Returns structured markdown, does NOT write files.
+tools: Read, WebSearch, WebFetch, Bash
+---
+
+# External Research Agent
+
+## Role
+You perform targeted external research using web search to gather API details, design patterns, architecture approaches, best practices, and technology evaluations. You synthesize findings into structured, actionable markdown for downstream analysis workflows.
+
+Spawned by: analyze-with-file (Phase 2), brainstorm-with-file, or any workflow needing external context.
+
+**CRITICAL**: Return structured markdown only. Do NOT write any files unless explicitly instructed in the prompt.
+
+## Process
+
+1. **Parse research objective** — Understand the topic, focus area, and what the caller needs
+2. **Plan queries** — Design 3-5 focused search queries targeting the objective
+3. **Execute searches** — Use `WebSearch` for general research, `WebFetch` for specific documentation pages
+4. **Cross-reference** — If codebase files are provided in prompt, `Read` them to ground research in actual code context
+5. **Synthesize findings** — Extract key insights, patterns, and recommendations from search results
+6. **Return structured output** — Markdown-formatted research findings
+
+## Research Modes
+
+### Detail Verification (default for analyze)
+Focus: verify assumptions, check best practices, validate technology choices, confirm patterns.
+Queries target: benchmarks, production postmortems, known issues, compatibility matrices, official docs.
+
+### API Research (for implementation planning)
+Focus: concrete API details, library versions, integration patterns, configuration options.
+Queries target: official documentation, API references, migration guides, changelog entries.
+
+### Design Research (for brainstorm/architecture)
+Focus: design alternatives, architecture patterns, competitive analysis, UX patterns.
+Queries target: design systems, pattern libraries, case studies, comparison articles.
+
+## Execution
+
+### Query Strategy
+```
+1. Parse topic → extract key technologies, patterns, concepts
+2. Generate 3-5 queries:
+   - Q1: "{technology} best practices {year}"
+   - Q2: "{pattern} vs {alternative} comparison"
+   - Q3: "{technology} known issues production"
+   - Q4: "{specific API/library} documentation {version}"
+   - Q5: "{domain} architecture patterns"
+3. Execute queries via WebSearch
+4. For promising results, WebFetch full content for detail extraction
+5. Synthesize across all sources
+```
+
+### Codebase Grounding
+When the prompt includes `codebase_context` (file paths, patterns, tech stack):
+- Read referenced files to understand actual usage
+- Compare external best practices against current implementation
+- Flag gaps between current code and recommended patterns
+
+## Output Format
+
+Return structured markdown (do NOT write files):
+
+```markdown
+## Research: {topic}
+
+### Key Findings
+- **{Finding 1}**: {detail} (confidence: HIGH|MEDIUM|LOW, source: {url_or_reference})
+- **{Finding 2}**: {detail} (confidence: HIGH|MEDIUM|LOW, source: {url_or_reference})
+
+### Technology / API Details
+- **{Library/API}**: version {X}, {key capabilities}
+  - Integration: {how to integrate}
+  - Caveats: {known issues or limitations}
+
+### Best Practices
+- {Practice 1}: {rationale} (source: {reference})
+- {Practice 2}: {rationale} (source: {reference})
+
+### Recommended Approach
+{Prescriptive recommendation with rationale — "use X" not "consider X or Y" when evidence is strong}
+
+### Alternatives Considered
+| Option | Pros | Cons | Verdict |
+|--------|------|------|---------|
+| {A} | ... | ... | Recommended / Viable / Avoid |
+
+### Pitfalls & Known Issues
+- {Issue 1}: {mitigation} (source: {reference})
+
+### Codebase Gaps (if codebase_context provided)
+- {Gap}: current code does {X}, best practice recommends {Y}
+
+### Sources
+- {source title}: {url} — {key takeaway}
+```
+
+## Error Handling
+- If WebSearch returns no results for a query: note "no results" and proceed with remaining queries
+- If WebFetch fails for a URL: skip and note the intended lookup
+- If all searches fail: return "research unavailable — proceed with codebase-only analysis" and list the queries that were attempted
+- If codebase files referenced in prompt don't exist: proceed with external research only
+
+## Constraints
+- Be prescriptive ("use X") not exploratory ("consider X or Y") when evidence is strong
+- Assign confidence levels (HIGH/MEDIUM/LOW) to all findings
+- Cite sources for claims — include URLs
+- Keep output under 200 lines
+- Do NOT write any files — return structured markdown only
+- Do NOT fabricate URLs or sources — only cite actual search results
+- Bash calls MUST use `run_in_background: false` (subagent cannot receive hook callbacks)

package/.claude/commands/workflow/analyze-with-file.md

@@ -10,11 +10,11 @@ allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glo
 When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analysis angles.
 
 <purpose>
-Interactive collaborative analysis workflow combining codebase exploration (cli-explore-agent) with CLI-assisted analysis (Gemini/Codex). Produces a documented discussion timeline with evolving understanding, decision trails, and actionable conclusions.
+Interactive collaborative analysis workflow combining codebase exploration (cli-explore-agent), external research (workflow-research-agent), and CLI-assisted analysis (Gemini/Codex). Produces a documented discussion timeline with evolving understanding, decision trails, and actionable conclusions.
 
 Invoked when user needs deep, multi-perspective analysis of a topic or codebase question — e.g., architecture review, implementation analysis, concept exploration, or decision evaluation.
 
-Produces: `discussion.md` (evolving analysis document with TOC, rounds, narrative synthesis), `explorations.json`/`perspectives.json` (structured findings), `conclusions.json` (final synthesis with recommendations). All artifacts stored in `.workflow/.analysis/{session-id}/`.
+Produces: `discussion.md` (evolving analysis document with TOC, rounds, narrative synthesis), `explorations.json`/`perspectives.json` (structured findings), `research.json` (external research findings), `conclusions.json` (final synthesis with recommendations). All artifacts stored in `.workflow/.analysis/{session-id}/`.
 </purpose>
 
 <conventions>
@@ -78,10 +78,11 @@ All `AskUserQuestion` calls MUST comply:
 |-------|----------|-------------|
 | 1 | `discussion.md` | Initialized with TOC, Current Understanding block, timeline, metadata |
 | 1 | Session variables | Dimensions, focus areas, analysis depth |
-| 2 | `exploration-codebase.json` | Single codebase context from cli-explore-agent |
-| 2 | `explorations/*.json` | Multi-perspective codebase explorations (parallel, up to 4) |
-| 2 | `explorations.json` | Single perspective aggregated findings |
-| 2 | `perspectives.json` | Multi-perspective findings (up to 4) with synthesis |
+| 2 | `exploration-codebase.json` | Shared Layer 1 discovery (files, modules, patterns) — always created |
+| 2 | `explorations/*.json` | Per-perspective Layer 2-3 deep-dives (multi-perspective only, max 4) |
+| 2 | `research.json` | External research findings (best practices, API details, known issues) — from workflow-research-agent |
+| 2 | `explorations.json` | Single perspective aggregated findings (Layer 1 + CLI analysis + research) |
+| 2 | `perspectives.json` | Multi-perspective findings (Layer 1 shared + per-perspective deep-dives + research) with synthesis |
 | 2 | Updated `discussion.md` | Round 1 + Initial Intent Coverage Check + Current Understanding replaced |
 | 3 | Updated `discussion.md` | Round 2-N: feedback, insights, narrative synthesis; TOC + Current Understanding updated each round |
 | 4 | `conclusions.json` | Final synthesis with recommendations (incl. steps[] + review_status) |
@@ -141,98 +142,179 @@ All `AskUserQuestion` calls MUST comply:
 <step name="cli_exploration">
 **Phase 2: Codebase exploration FIRST, then CLI analysis.**
 
-**Step 1: Codebase Exploration** (cli-explore-agent, parallel up to 6)
+**Step 1: Codebase Exploration** (cli-explore-agent, 1 shared + N perspective-specific)
 
-- **Single**: General codebase analysis -> `{sessionFolder}/exploration-codebase.json`
-- **Multi-perspective**: Parallel per-perspective -> `{sessionFolder}/explorations/{perspective}.json`
-- **Common tasks**: `ccw tool exec get_modules_by_depth '{}'`, keyword searches, read `.workflow/project-tech.json`
+Two-phase approach to avoid redundant file discovery:
+
+**Phase A — Shared Discovery** (1 agent, always runs):
+One cli-explore-agent performs Layer 1 (breadth) for ALL perspectives -> `{sessionFolder}/exploration-codebase.json`
 
 ```javascript
-// Template for cli-explore-agent (single or per-perspective)
+// Shared Layer 1 discovery — runs ONCE regardless of perspective count
 Agent({
   subagent_type: "cli-explore-agent",
   run_in_background: false,
-  description: `Explore codebase: ${topicSlug}`,
+  description: `Discover codebase: ${topicSlug}`,
   prompt: `
 ## Analysis Context
 Topic: ${topic_or_question}
 Dimensions: ${dimensions.join(', ')}
-// For multi-perspective, add: Perspective: ${perspective.name} - ${perspective.focus}
 Session: ${sessionFolder}
 
 ## MANDATORY FIRST STEPS
 1. Run: ccw tool exec get_modules_by_depth '{}'
 2. Read: .workflow/project-tech.json (if exists)
 
-## Layered Exploration (MUST follow all 3 layers)
+## Layer 1 — Module Discovery (Breadth ONLY)
+- Search by topic keywords across ALL dimensions: ${dimensions.join(', ')}
+- Identify ALL relevant files, map module boundaries and entry points
+- Categorize files by dimension/perspective relevance
+- Output: relevant_files[] with annotations + dimension tags, initial patterns[]
+
+## Output
+Write to: ${sessionFolder}/exploration-codebase.json
+Schema: {relevant_files: [{path, annotation, dimensions[]}], patterns[], module_map: {}, questions_for_user, _metadata}
+`
+})
+```
+
+**Phase A2 — External Research** (parallel with Phase A, runs when topic involves technologies/patterns/APIs):
+
+Determine if external research would add value — skip for purely internal codebase questions (e.g., "how does module X work"), run for topics involving technology choices, best practices, architecture patterns, API usage, or comparison with industry standards.
 
-### Layer 1 — Module Discovery (Breadth)
-- Search by topic keywords, identify ALL relevant files
-- Map module boundaries and entry points -> relevant_files[] with annotations
+```javascript
+// External research — runs in PARALLEL with Phase A codebase exploration
+// Skip if topic is purely internal codebase navigation
+const needsResearch = dimensions.some(d =>
+  ['architecture', 'comparison', 'decision', 'performance', 'security'].includes(d)
+) || topic_or_question.match(/best practice|pattern|vs|compare|approach|standard|library|framework/i)
+
+if (needsResearch) {
+  Agent({
+    subagent_type: "workflow-research-agent",
+    run_in_background: false,
+    description: `Research: ${topicSlug}`,
+    prompt: `
+## Research Objective
+Topic: ${topic_or_question}
+Mode: detail-verification
+Dimensions: ${dimensions.join(', ')}
+
+## Focus
+${dimensions.includes('architecture') ? '- Architecture patterns and best practices for this domain' : ''}
+${dimensions.includes('performance') ? '- Performance benchmarks and optimization patterns' : ''}
+${dimensions.includes('security') ? '- Security best practices and known vulnerabilities' : ''}
+${dimensions.includes('comparison') ? '- Technology comparison and trade-off analysis' : ''}
+${dimensions.includes('decision') ? '- Decision frameworks and industry recommendations' : ''}
+- Verify assumptions about technologies/patterns involved
+- Known issues and pitfalls in this area
+- Recommended approaches with evidence
+
+## Codebase Context (from Phase A if available)
+Tech stack: ${techStack || 'detect from project files'}
+Key patterns observed: ${sharedDiscovery?.patterns?.join(', ') || 'pending Phase A results'}
+
+## Output
+Return structured markdown per your output format.
+Do NOT write files.
+`
+  })
+  // Parse research agent output → save to ${sessionFolder}/research.json
+  // Schema: {topic, mode, findings[], best_practices[], alternatives[], pitfalls[], sources[], _metadata}
+}
+```
 
-### Layer 2 — Structure Tracing (Depth)
-- Top 3-5 key files: trace call chains 2-3 levels deep
+**Phase B — Perspective Deep-Dive** (parallel, only for multi-perspective, max 4):
+Each perspective agent receives shared Layer 1 results, performs only Layer 2-3 on its relevant subset.
+Skip if single-perspective (single mode proceeds directly to Step 2 CLI analysis with Layer 1 results).
+
+```javascript
+// Per-perspective Layer 2-3 — receives shared discovery, avoids re-scanning
+// Only runs in multi-perspective mode
+const sharedDiscovery = readJSON(`${sessionFolder}/exploration-codebase.json`)
+const perspectiveFiles = sharedDiscovery.relevant_files
+  .filter(f => f.dimensions.includes(perspective.dimension))
+
+selectedPerspectives.forEach(perspective => {
+  Agent({
+    subagent_type: "cli-explore-agent",
+    run_in_background: false,
+    description: `Deep-dive: ${perspective.name}`,
+    prompt: `
+## Analysis Context
+Topic: ${topic_or_question}
+Perspective: ${perspective.name} - ${perspective.focus}
+Session: ${sessionFolder}
+
+## SHARED DISCOVERY (Layer 1 already completed — DO NOT re-scan)
+Relevant files for this perspective:
+${perspectiveFiles.map(f => `- ${f.path}: ${f.annotation}`).join('\n')}
+Patterns found: ${sharedDiscovery.patterns.join(', ')}
+
+## Layer 2 — Structure Tracing (Depth)
+- From the relevant files above, pick top 3-5 key files for this perspective
+- Trace call chains 2-3 levels deep
 - Identify data flow paths and dependencies -> call_chains[], data_flows[]
 
-### Layer 3 — Code Anchor Extraction (Detail)
+## Layer 3 — Code Anchor Extraction (Detail)
 - Each key finding: extract code snippet (20-50 lines) with file:line
-- Annotate WHY this matters -> code_anchors[]
+- Annotate WHY this matters for ${perspective.name} -> code_anchors[]
 
 ## Output
-Write to: ${sessionFolder}/exploration-codebase.json
-// Multi-perspective: ${sessionFolder}/explorations/${perspective.name}.json
-
-Schema: {relevant_files, patterns, key_findings, code_anchors: [{file, lines, snippet, significance}], call_chains: [{entry, chain, files}], questions_for_user, _metadata}
+Write to: ${sessionFolder}/explorations/${perspective.name}.json
+Schema: {perspective, relevant_files, key_findings, code_anchors: [{file, lines, snippet, significance}], call_chains: [{entry, chain, files}], questions_for_user, _metadata}
 `
+  })
 })
 ```
 
-**Step 2: CLI Analysis** (AFTER exploration)
+**Step 2: CLI Deep Analysis** (AFTER exploration, single-perspective ONLY)
 
-- **Single**: Comprehensive CLI analysis with exploration context
-- **Multi (up to 4)**: Parallel CLI calls per perspective
+- **Single-perspective**: CLI does Layer 2-3 depth analysis (explore agent only did Layer 1)
+- **Multi-perspective**: SKIP this step — perspective agents in Step 1 Phase B already did Layer 2-3
 - Execution: `Bash` with `run_in_background: true`
 
 ```javascript
-// Build shared exploration context for CLI prompts
-const explorationContext = `
-PRIOR EXPLORATION CONTEXT:
-- Key files: ${explorationResults.relevant_files.slice(0,5).map(f => f.path).join(', ')}
-- Patterns: ${explorationResults.patterns.slice(0,3).join(', ')}
-- Findings: ${explorationResults.key_findings.slice(0,3).join(', ')}
-- Code anchors:
-${(explorationResults.code_anchors || []).slice(0,5).map(a => `  [${a.file}:${a.lines}] ${a.significance}\n  \`\`\`\n  ${a.snippet}\n  \`\`\``).join('\n')}
-- Call chains: ${(explorationResults.call_chains || []).slice(0,3).map(c => `${c.entry} -> ${c.chain.join(' -> ')}`).join('; ')}`
-
-// Single perspective (for multi: loop selectedPerspectives with perspective.purpose/tasks/constraints)
-Bash({
-  command: `ccw cli -p "
-PURPOSE: Analyze '${topic_or_question}' from ${dimensions.join(', ')} perspectives
-Success: Actionable insights with clear reasoning
+// ONLY for single-perspective mode — multi-perspective already has deep-dive agents
+if (selectedPerspectives.length <= 1) {
+  const sharedDiscovery = readJSON(`${sessionFolder}/exploration-codebase.json`)
+  const explorationContext = `
+PRIOR EXPLORATION (Layer 1 discovery):
+- Key files: ${sharedDiscovery.relevant_files.slice(0,8).map(f => `${f.path} (${f.annotation})`).join(', ')}
+- Patterns: ${sharedDiscovery.patterns.slice(0,5).join(', ')}
+- Module map: ${JSON.stringify(sharedDiscovery.module_map || {})}`
+
+  Bash({
+    command: `ccw cli -p "
+PURPOSE: Deep analysis of '${topic_or_question}' — build on prior file discovery
+Success: Actionable insights with code evidence (anchors + call chains)
 
 ${explorationContext}
 
 TASK:
-- Build on exploration findings — reference specific code anchors
-- Analyze common patterns and anti-patterns with code evidence
-- Highlight potential issues/opportunities with file:line references
+- From discovered files, trace call chains 2-3 levels deep for top 3-5 key files
+- Extract code snippets (20-50 lines) for each key finding with file:line
+- Identify patterns, anti-patterns, and potential issues with evidence
 - Generate discussion points for user clarification
 
 MODE: analysis
 CONTEXT: @**/* | Topic: ${topic_or_question}
-EXPECTED: Structured analysis with sections, insights tied to evidence, questions, recommendations
-CONSTRAINTS: Focus on ${dimensions.join(', ')}
+EXPECTED: Structured analysis with: key_findings[], code_anchors[{file,lines,snippet,significance}], call_chains[{entry,chain,files}], discussion_points[]
+CONSTRAINTS: Focus on ${dimensions.join(', ')} | Do NOT re-discover files — use provided file list
 " --tool gemini --mode analysis`,
-  run_in_background: true
-})
-// STOP: Wait for hook callback before continuing
-// Multi-perspective: Same pattern per perspective with perspective.purpose/tasks/constraints/tool
+    run_in_background: true
+  })
+  // STOP: Wait for hook callback before continuing
+}
 ```
 
 **Step 3: Aggregate Findings**
-- Consolidate explorations + CLI results
+- Consolidate explorations + CLI results + research findings (if research.json exists)
+- Merge research best_practices[] and pitfalls[] into discussion points
+- Cross-reference: flag gaps where codebase patterns diverge from research best practices
 - Multi: Extract synthesis (convergent themes, conflicting views, unique contributions)
 - Write to `explorations.json` (single) or `perspectives.json` (multi)
+- If research.json exists, add `external_research` section to explorations/perspectives with: key findings, best practices, codebase gaps
 
 **Step 4: Update discussion.md** — Append Round 1 with sources, key findings, discussion points, open questions
 
@@ -243,18 +325,36 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 - Present to user at beginning of Phase 3: "初始探索完成后，以下意图的覆盖情况：[list]。接下来的讨论将重点关注未覆盖的部分。"
 - Purpose: Early course correction — catch drift before spending multiple interactive rounds
 
-**explorations.json Schema** (single):
+**exploration-codebase.json Schema** (shared Layer 1):
+- `session_id`, `timestamp`, `topic`, `dimensions[]`
+- `relevant_files[]`: {path, annotation, dimensions[]}
+- `patterns[]`, `module_map`: {}
+- `questions_for_user[]`, `_metadata`
+
+**research.json Schema** (external research findings):
+- `topic`, `mode` (detail-verification|api-research|design-research), `timestamp`
+- `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, results_found}
+
+**explorations.json Schema** (single — Layer 1 + CLI analysis + research merged):
 - `session_id`, `timestamp`, `topic`, `dimensions[]`
 - `sources[]`: {type, file/summary}
 - `key_findings[]`, `code_anchors[]`: {file, lines, snippet, significance}
 - `call_chains[]`: {entry, chain, files}
 - `discussion_points[]`, `open_questions[]`
 - `technical_solutions[]`: {round, solution, problem, rationale, alternatives, status: proposed|validated|rejected, evidence_refs[], next_action}
+- `external_research`: {findings[], best_practices[], codebase_gaps[], sources[]} — merged from research.json if available
 
-**perspectives.json Schema** (multi — extends explorations.json):
-- `perspectives[]`: [{name, tool, findings, insights, questions}]
+**perspectives.json Schema** (multi — Layer 1 shared + per-perspective Layer 2-3 + research):
+- `shared_discovery`: {relevant_files[], patterns[], module_map}
+- `perspectives[]`: [{name, tool, findings, insights, questions, code_anchors[], call_chains[]}]
+- `external_research`: {findings[], best_practices[], codebase_gaps[], sources[]} — merged from research.json if available
 - `synthesis`: {convergent_themes, conflicting_views, unique_contributions}
-- code_anchors/call_chains include `perspective` field
 
 | Condition | Action |
 |-----------|--------|
@@ -270,6 +370,22 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 
 **Guideline**: Delegate complex tasks to agents (cli-explore-agent) or CLI calls. Avoid direct analysis in main process.
 
+**Cumulative Context Rule**: Every agent/CLI call in Phase 3 MUST include a summary of ALL prior exploration results to avoid re-discovering known information. Build `priorContext` before each call:
+```javascript
+// Build cumulative context from all prior explorations (Phase 2 + previous rounds)
+const allFindings = readJSON(`${sessionFolder}/explorations.json`) // or perspectives.json
+const priorContext = `
+## KNOWN FINDINGS (DO NOT re-discover)
+- Established files: ${allFindings.sources.map(s => s.file).join(', ')}
+- Key findings: ${allFindings.key_findings.join('; ')}
+- Code anchors: ${allFindings.code_anchors.slice(0,5).map(a => `${a.file}:${a.lines}`).join(', ')}
+- Call chains: ${allFindings.call_chains.slice(0,3).map(c => c.entry).join(', ')}
+- Open questions: ${allFindings.open_questions.join('; ')}
+
+## NEW TASK: Focus ONLY on unexplored areas below.
+`
+```
+
 **Loop** (max 5 rounds):
 
 1. **Current Understanding Summary** (Round >= 2, BEFORE presenting new findings):
@@ -280,8 +396,8 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 
 3. **Gather Feedback** (AskUserQuestion, single-select, header: "分析反馈"):
    - **继续深入**: Direction correct — deepen automatically or user specifies direction (combines agree+deepen and agree+suggest)
+   - **外部研究**: Need external research on specific technology/pattern/best practice (spawns workflow-research-agent)
    - **调整方向**: Different focus or specific questions to address
-   - **补充信息**: User has additional context, constraints, or corrections to provide
    - **分析完成**: Sufficient -> exit to Phase 4
 
 4. **Process Response** (always record user choice + impact to discussion.md):
@@ -293,9 +409,14 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
    - **"Other" is auto-provided** by AskUserQuestion — covers user-specified custom direction (no need for separate "suggest next step" option)
    - Execute selected direction -> merge new code_anchors/call_chains -> record confirmed assumptions + deepen angle
 
-   **调整方向** -> AskUserQuestion (header: "新方向", user selects or provides custom via "Other") -> new CLI exploration -> Record Decision (old vs new direction, reason, impact)
+   **外部研究** -> Spawn workflow-research-agent for targeted research:
+   - AskUserQuestion (header: "研究主题", freetext via "Other"): What specific technology/pattern/approach needs external research?
+   - Spawn research agent with topic + current codebase context (from explorations.json)
+   - Merge research findings into explorations.json `external_research` section
+   - Update research.json with new findings (append, don't overwrite)
+   - Record research findings as Key Findings in discussion.md
 
-   **补充信息** -> Capture user input, integrate into context, answer questions via CLI/analysis if needed -> Record corrections/additions + updated understanding
+   **调整方向** -> AskUserQuestion (header: "新方向", user selects or provides custom via "Other") -> new CLI exploration -> Record Decision (old vs new direction, reason, impact)
 
    **分析完成** -> Exit loop -> Record why concluding
 
@@ -525,6 +646,8 @@ ${implScope.map((item, i) => `${i+1}. **${item.objective}** [${item.priority}]
 | E005 | error | No relevant findings from exploration — broaden search, ask user for clarification | cli_exploration |
 | E006 | warning | Session folder conflict — append timestamp suffix | session_init |
 | E007 | error | Gemini unavailable — fallback to Codex or manual analysis | cli_exploration |
+| E008 | warning | Research agent WebSearch failed — continue with codebase-only analysis, note limitation | cli_exploration |
+| E009 | warning | Research findings conflict with codebase patterns — flag as codebase_gaps for user review | cli_exploration |
 
 </error_codes>
 
@@ -534,6 +657,8 @@ ${implScope.map((item, i) => `${i+1}. **${item.objective}** [${item.priority}]
 - [ ] Dimensions identified and user preferences captured (Phase 1)
 - [ ] discussion.md initialized with TOC, Current Understanding, metadata
 - [ ] Codebase exploration completed with code_anchors and call_chains (Phase 2)
+- [ ] External research executed if topic warrants it (architecture/comparison/decision/performance/security dimensions)
+- [ ] Research findings merged into explorations/perspectives with codebase_gaps flagged
 - [ ] CLI analysis executed and findings aggregated
 - [ ] Initial Intent Coverage Check appended to discussion.md
 - [ ] Interactive discussion rounds documented with narrative synthesis (Phase 3)