claude-code-workflow 6.3.54 → 7.0.0

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

@@ -9,252 +9,228 @@ allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob
 
 When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analysis angles.
 
-# Workflow Analyze-With-File Command (/workflow:analyze-with-file)
+# Workflow Analyze Command
 
-## Overview
-
-Interactive collaborative analysis workflow with **documented discussion process**. Records understanding evolution, facilitates multi-round Q&A, and uses CLI tools (Gemini/Codex) for deep exploration.
-
-**Core workflow**: Topic → Explore → Discuss → Document → Refine → Conclude
-
-**Key features**:
-- **discussion.md**: Timeline of discussions and understanding evolution
-- **Multi-round Q&A**: Iterative clarification with user
-- **CLI-assisted exploration**: Gemini/Codex for codebase and concept analysis
-- **Consolidated insights**: Synthesizes discussions into actionable conclusions
-- **Flexible continuation**: Resume analysis sessions to build on previous work
-
-## Usage
+## Quick Start
 
 ```bash
-/workflow:analyze-with-file [FLAGS] <TOPIC_OR_QUESTION>
-
-# Flags
--y, --yes              Skip confirmations, use recommended settings
--c, --continue         Continue existing session (auto-detected if exists)
-
-# Arguments
-<topic-or-question>    Analysis topic, question, or concept to explore (required)
-
-# Examples
+# Basic usage
 /workflow:analyze-with-file "如何优化这个项目的认证架构"
-/workflow:analyze-with-file --continue "认证架构"              # Continue existing session
-/workflow:analyze-with-file -y "性能瓶颈分析"                  # Auto mode
-```
 
-## Execution Process
-
-```
-Session Detection:
-   ├─ Check if analysis session exists for topic
-   ├─ EXISTS + discussion.md exists → Continue mode
-   └─ NOT_FOUND → New session mode
-
-Phase 1: Topic Understanding
-   ├─ Parse topic/question
-   ├─ Identify analysis dimensions (architecture, implementation, concept, etc.)
-   ├─ Initial scoping with user (AskUserQuestion)
-   └─ Document initial understanding in discussion.md
-
-Phase 2: CLI Exploration (Parallel)
-   ├─ Launch cli-explore-agent for codebase context
-   ├─ Use Gemini/Codex for deep analysis
-   └─ Aggregate findings into exploration summary
-
-Phase 3: Interactive Discussion (Multi-Round)
-   ├─ Present exploration findings
-   ├─ Facilitate Q&A with user (AskUserQuestion)
-   ├─ Capture user insights and requirements
-   ├─ Update discussion.md with each round
-   └─ Repeat until user is satisfied or clarity achieved
-
-Phase 4: Synthesis & Conclusion
-   ├─ Consolidate all insights
-   ├─ Update discussion.md with conclusions
-   ├─ Generate actionable recommendations
-   └─ Optional: Create follow-up tasks or issues
-
-Output:
-   ├─ .workflow/.analysis/{slug}-{date}/discussion.md (evolving document)
-   ├─ .workflow/.analysis/{slug}-{date}/explorations.json (CLI findings)
-   └─ .workflow/.analysis/{slug}-{date}/conclusions.json (final synthesis)
+# With options
+/workflow:analyze-with-file --continue "认证架构"    # Continue existing session
+/workflow:analyze-with-file -y "性能瓶颈分析"        # Auto mode
 ```
 
-## Implementation
+**Context Source**: cli-explore-agent + Gemini/Codex analysis
+**Output Directory**: `.workflow/.analysis/{session-id}/`
+**Core Innovation**: Documented discussion timeline with evolving understanding
 
-### Session Setup & Mode Detection
+## Output Artifacts
 
-```javascript
-const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+### Phase 1: Topic Understanding
 
-const topicSlug = topic_or_question.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-').substring(0, 40)
-const dateStr = getUtc8ISOString().substring(0, 10)
+| Artifact | Description |
+|----------|-------------|
+| `discussion.md` | Evolution of understanding & discussions (initialized) |
+| Session variables | Dimensions, focus areas, analysis depth |
 
-const sessionId = `ANL-${topicSlug}-${dateStr}`
-const sessionFolder = `.workflow/.analysis/${sessionId}`
-const discussionPath = `${sessionFolder}/discussion.md`
-const explorationsPath = `${sessionFolder}/explorations.json`
-const conclusionsPath = `${sessionFolder}/conclusions.json`
+### Phase 2: CLI Exploration
 
-// Auto-detect mode
-const sessionExists = fs.existsSync(sessionFolder)
-const hasDiscussion = sessionExists && fs.existsSync(discussionPath)
-const forcesContinue = $ARGUMENTS.includes('--continue') || $ARGUMENTS.includes('-c')
+| Artifact | Description |
+|----------|-------------|
+| `exploration-codebase.json` | Single codebase context from cli-explore-agent |
+| `explorations/*.json` | Multi-perspective codebase explorations (parallel, up to 4) |
+| `explorations.json` | Single perspective aggregated findings |
+| `perspectives.json` | Multi-perspective findings (up to 4 perspectives) with synthesis |
+| Updated `discussion.md` | Round 1 with exploration results |
 
-const mode = (hasDiscussion || forcesContinue) ? 'continue' : 'new'
+### Phase 3: Interactive Discussion
 
-if (!sessionExists) {
-  bash(`mkdir -p ${sessionFolder}`)
-}
-```
+| Artifact | Description |
+|----------|-------------|
+| Updated `discussion.md` | Round 2-N with user feedback and insights |
+| Corrected assumptions | Tracked in discussion timeline |
 
----
+### Phase 4: Synthesis & Conclusion
 
-### Phase 1: Topic Understanding
+| Artifact | Description |
+|----------|-------------|
+| `conclusions.json` | Final synthesis with recommendations |
+| Final `discussion.md` | ⭐ Complete analysis with conclusions |
 
-**Step 1.1: Parse Topic & Identify Dimensions**
+## Overview
 
-```javascript
-// Analyze topic to determine analysis dimensions
-const ANALYSIS_DIMENSIONS = {
-  architecture: ['架构', 'architecture', 'design', 'structure', '设计'],
-  implementation: ['实现', 'implement', 'code', 'coding', '代码'],
-  performance: ['性能', 'performance', 'optimize', 'bottleneck', '优化'],
-  security: ['安全', 'security', 'auth', 'permission', '权限'],
-  concept: ['概念', 'concept', 'theory', 'principle', '原理'],
-  comparison: ['比较', 'compare', 'vs', 'difference', '区别'],
-  decision: ['决策', 'decision', 'choice', 'tradeoff', '选择']
-}
-
-function identifyDimensions(topic) {
-  const text = topic.toLowerCase()
-  const matched = []
-
-  for (const [dimension, keywords] of Object.entries(ANALYSIS_DIMENSIONS)) {
-    if (keywords.some(k => text.includes(k))) {
-      matched.push(dimension)
-    }
-  }
-
-  return matched.length > 0 ? matched : ['general']
-}
-
-const dimensions = identifyDimensions(topic_or_question)
-```
+Interactive collaborative analysis workflow with **documented discussion process**. Records understanding evolution, facilitates multi-round Q&A, and uses CLI tools for deep exploration.
 
-**Step 1.2: Initial Scoping (New Session Only)**
+**Core workflow**: Topic → Explore → Discuss → Document → Refine → Conclude
 
-```javascript
-const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
-
-if (mode === 'new' && !autoYes) {
-  // Ask user to scope the analysis
-  AskUserQuestion({
-    questions: [
-      {
-        question: `分析范围: "${topic_or_question}"\n\n您想重点关注哪些方面?`,
-        header: "Focus",
-        multiSelect: true,
-        options: [
-          { label: "代码实现", description: "分析现有代码实现" },
-          { label: "架构设计", description: "架构层面的分析" },
-          { label: "最佳实践", description: "行业最佳实践对比" },
-          { label: "问题诊断", description: "识别潜在问题" }
-        ]
-      },
-      {
-        question: "分析深度?",
-        header: "Depth",
-        multiSelect: false,
-        options: [
-          { label: "Quick Overview", description: "快速概览 (10-15分钟)" },
-          { label: "Standard Analysis", description: "标准分析 (30-60分钟)" },
-          { label: "Deep Dive", description: "深度分析 (1-2小时)" }
-        ]
-      }
-    ]
-  })
-}
-```
+### Decision Recording Protocol
+
+**⚠️ CRITICAL**: During analysis, the following situations **MUST** trigger immediate recording to discussion.md:
 
-**Step 1.3: Create/Update discussion.md**
+| Trigger | What to Record | Target Section |
+|---------|---------------|----------------|
+| **Direction choice** | What was chosen, why, what alternatives were discarded | `#### Decision Log` |
+| **Key finding** | Finding content, impact scope, confidence level | `#### Key Findings` |
+| **Assumption change** | Old assumption → new understanding, reason for change, impact | `#### Corrected Assumptions` |
+| **User feedback** | User's original input, rationale for adoption/adjustment | `#### User Input` |
+| **Disagreement & trade-off** | Conflicting viewpoints, trade-off basis, final choice | `#### Decision Log` |
+| **Scope adjustment** | Before/after scope, trigger reason for adjustment | `#### Decision Log` |
 
-For new session:
+**Decision Record Format**:
 ```markdown
-# Analysis Discussion
+> **Decision**: [Description of the decision]
+> - **Context**: [What triggered this decision]
+> - **Options considered**: [Alternatives evaluated]
+> - **Chosen**: [Selected approach] — **Reason**: [Rationale]
+> - **Impact**: [Effect on analysis direction/conclusions]
+```
 
-**Session ID**: ${sessionId}
-**Topic**: ${topic_or_question}
-**Started**: ${getUtc8ISOString()}
-**Dimensions**: ${dimensions.join(', ')}
+**Recording Principles**:
+- **Immediacy**: Record decisions as they happen, not at the end of a phase
+- **Completeness**: Capture context, options, chosen approach, and reason
+- **Traceability**: Later phases must be able to trace back why a decision was made
 
----
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    INTERACTIVE ANALYSIS WORKFLOW                         │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  Phase 1: Topic Understanding                                            │
+│     ├─ Parse topic/question                                              │
+│     ├─ Identify analysis dimensions (architecture, performance, etc.)    │
+│     ├─ Initial scoping with user                                         │
+│     └─ Initialize discussion.md                                          │
+│                                                                          │
+│  Phase 2: CLI Exploration                                                │
+│     ├─ Codebase Exploration (cli-explore-agent, supports parallel ≤4)    │
+│     ├─ Multi-Perspective Analysis (AFTER exploration)                    │
+│     │   ├─ Single: Comprehensive analysis                                │
+│     │   └─ Multi (≤4): Parallel perspectives with synthesis              │
+│     ├─ Aggregate findings                                                │
+│     └─ Update discussion.md with Round 1                                 │
+│                                                                          │
+│  Phase 3: Interactive Discussion (Multi-Round)                           │
+│     ├─ Present exploration findings                                      │
+│     ├─ Facilitate Q&A with user                                          │
+│     ├─ Capture user insights and corrections                             │
+│     ├─ Actions: Deepen | Adjust direction | Answer questions             │
+│     ├─ Update discussion.md with each round                              │
+│     └─ Repeat until clarity achieved (max 5 rounds)                      │
+│                                                                          │
+│  Phase 4: Synthesis & Conclusion                                         │
+│     ├─ Consolidate all insights                                          │
+│     ├─ Generate conclusions with recommendations                         │
+│     ├─ Update discussion.md with final synthesis                         │
+│     └─ Offer follow-up options (issue/task/report)                       │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
 
-## User Context
+## Output Structure
 
-**Focus Areas**: ${userFocusAreas.join(', ')}
-**Analysis Depth**: ${analysisDepth}
+```
+.workflow/.analysis/ANL-{slug}-{date}/
+├── discussion.md              # ⭐ Evolution of understanding & discussions
+├── exploration-codebase.json  # Phase 2: Single codebase context
+├── explorations/              # Phase 2: Multi-perspective codebase explorations (if selected)
+│   ├── technical.json
+│   └── architectural.json
+├── explorations.json          # Phase 2: Single perspective findings
+├── perspectives.json          # Phase 2: Multi-perspective findings (if selected)
+└── conclusions.json           # Phase 4: Final synthesis
+```
 
----
+## Implementation
 
-## Discussion Timeline
+### Session Initialization
 
-### Round 1 - Initial Understanding (${timestamp})
+**Objective**: Create session context and directory structure for analysis.
 
-#### Topic Analysis
+**Required Actions**:
+1. Extract topic/question from `$ARGUMENTS`
+2. Generate session ID: `ANL-{slug}-{date}`
+   - slug: lowercase, alphanumeric + Chinese, max 40 chars
+   - date: YYYY-MM-DD (UTC+8)
+3. Define session folder: `.workflow/.analysis/{session-id}`
+4. Parse command options:
+   - `-c` or `--continue` for session continuation
+   - `-y` or `--yes` for auto-approval mode
+5. Auto-detect mode: If session folder + discussion.md exist → continue mode
+6. Create directory structure: `{session-folder}/`
 
-Based on the topic "${topic_or_question}":
+**Session Variables**:
+- `sessionId`: Unique session identifier
+- `sessionFolder`: Base directory for all artifacts
+- `autoMode`: Boolean for auto-confirmation
+- `mode`: new | continue
 
-- **Primary dimensions**: ${dimensions.join(', ')}
-- **Initial scope**: ${initialScope}
-- **Key questions to explore**:
-  - ${question1}
-  - ${question2}
-  - ${question3}
+### Phase 1: Topic Understanding
 
-#### Next Steps
+**Objective**: Analyze topic, identify dimensions, gather user input, initialize discussion.md.
 
-- Launch CLI exploration for codebase context
-- Gather external insights via Gemini
-- Prepare discussion points for user
+**Prerequisites**:
+- Session initialized with valid sessionId and sessionFolder
+- Topic/question available from $ARGUMENTS
 
----
+**Workflow Steps**:
 
-## Current Understanding
+1. **Parse Topic & Identify Dimensions**
+   - Match topic keywords against ANALYSIS_DIMENSIONS
+   - Identify relevant dimensions: architecture, implementation, performance, security, concept, comparison, decision
+   - Default to "general" if no match
 
-${initialUnderstanding}
-```
+2. **Initial Scoping** (if new session + not auto mode)
+   - **Focus**: Multi-select from directions generated by detected dimensions (see Dimension-Direction Mapping)
+   - **Perspectives**: Multi-select up to 4 analysis perspectives (see Analysis Perspectives), default: single comprehensive view
+   - **Depth**: Single-select from Quick Overview (10-15min) / Standard Analysis (30-60min) / Deep Dive (1-2hr)
 
-For continue session, append:
-```markdown
-### Round ${n} - Continuation (${timestamp})
+3. **Initialize discussion.md**
+   - Create discussion.md with session metadata
+   - Add user context: focus areas, analysis depth
+   - Add initial understanding: dimensions, scope, key questions
+   - Create empty sections for discussion timeline
+   - **📌 Record initial decisions**: Document dimension selection rationale, excluded dimensions with reasons, intent behind user preferences
 
-#### Previous Context
+4. **📌 Record Phase 1 Decisions**
+   - Record why these dimensions were selected (keyword match + user confirmation)
+   - Record the rationale behind analysis depth selection
+   - If user adjusted recommended focus, record the adjustment reason
 
-Resuming analysis based on prior discussion.
+**Success Criteria**:
+- Session folder created with discussion.md initialized
+- Analysis dimensions identified
+- User preferences captured (focus, depth)
+- **Phase 1 decisions recorded** with context and rationale
 
-#### New Focus
+### Phase 2: CLI Exploration
 
-${newFocusFromUser}
-```
+**Objective**: Gather codebase context, then execute deep analysis via CLI tools.
 
----
+**Prerequisites**:
+- Phase 1 completed successfully
+- discussion.md initialized
+- Dimensions identified
 
-### Phase 2: CLI Exploration
+**Workflow Steps** (⚠️ Codebase exploration FIRST):
 
-**Step 2.1: Launch Parallel Explorations**
+1. **Codebase Exploration via cli-explore-agent** (supports parallel up to 4)
+   - Agent type: `cli-explore-agent`
+   - Execution mode: parallel if multi-perspective selected, otherwise single (run_in_background: false for sequential, true for parallel)
+   - **Single exploration**: General codebase analysis
+   - **Multi-perspective**: Parallel explorations per perspective focus (max 4, each with specific angle)
+   - **Common tasks**: Run `ccw tool exec get_modules_by_depth '{}'`, execute searches based on topic keywords, read `.workflow/project-tech.json`
+   - **Output**: `{sessionFolder}/exploration-codebase.json` (single) or `{sessionFolder}/explorations/{perspective}.json` (multi)
+   - **Purpose**: Enrich CLI prompts with codebase context for each perspective
 
+**Single Exploration Example**:
 ```javascript
-const explorationPromises = []
-
-// CLI Explore Agent for codebase
-if (dimensions.includes('implementation') || dimensions.includes('architecture')) {
-  explorationPromises.push(
-    Task(
-      subagent_type="cli-explore-agent",
-      run_in_background=false,
-      description=`Explore codebase: ${topicSlug}`,
-      prompt=`
+Task({
+  subagent_type: "cli-explore-agent",
+  run_in_background: false,
+  description: `Explore codebase: ${topicSlug}`,
+  prompt: `
 ## Analysis Context
 Topic: ${topic_or_question}
 Dimensions: ${dimensions.join(', ')}
@@ -271,492 +247,436 @@ ${dimensions.map(d => `- ${d}: Identify relevant code patterns and structures`).
 ## Output
 Write findings to: ${sessionFolder}/exploration-codebase.json
 
-Schema:
-{
-  "relevant_files": [{path, relevance, rationale}],
-  "patterns": [],
-  "key_findings": [],
-  "questions_for_user": [],
-  "_metadata": { "exploration_type": "codebase", "timestamp": "..." }
-}
+Schema: {relevant_files, patterns, key_findings, questions_for_user, _metadata}
 `
-    )
-  )
-}
-
-// Gemini CLI for deep analysis
-explorationPromises.push(
-  Bash({
-    command: `ccw cli -p "
-PURPOSE: Analyze topic '${topic_or_question}' from ${dimensions.join(', ')} perspectives
-Success criteria: Actionable insights with clear reasoning
-
-TASK:
-• Identify key considerations for this topic
-• Analyze common patterns and anti-patterns
-• Highlight potential issues or opportunities
-• Generate discussion points for user clarification
-
-MODE: analysis
-
-CONTEXT: @**/* | Topic: ${topic_or_question}
-
-EXPECTED:
-- Structured analysis with clear sections
-- Specific insights tied to evidence
-- Questions to deepen understanding
-- Recommendations with rationale
-
-CONSTRAINTS: Focus on ${dimensions.join(', ')}
-" --tool gemini --mode analysis`,
-    run_in_background: true
-  })
-)
+})
 ```
 
-**Step 2.2: Aggregate Findings**
-
+**Multi-Perspective Parallel Example** (up to 4 agents):
 ```javascript
-// After explorations complete, aggregate into explorations.json
-const explorations = {
-  session_id: sessionId,
-  timestamp: getUtc8ISOString(),
-  topic: topic_or_question,
-  dimensions: dimensions,
-  sources: [
-    { type: "codebase", file: "exploration-codebase.json" },
-    { type: "gemini", summary: geminiOutput }
-  ],
-  key_findings: [...],
-  discussion_points: [...],
-  open_questions: [...]
-}
-
-Write(explorationsPath, JSON.stringify(explorations, null, 2))
-```
-
-**Step 2.3: Update discussion.md**
-
-```markdown
-#### Exploration Results (${timestamp})
-
-**Sources Analyzed**:
-${sources.map(s => `- ${s.type}: ${s.summary}`).join('\n')}
-
-**Key Findings**:
-${keyFindings.map((f, i) => `${i+1}. ${f}`).join('\n')}
-
-**Points for Discussion**:
-${discussionPoints.map((p, i) => `${i+1}. ${p}`).join('\n')}
-
-**Open Questions**:
-${openQuestions.map((q, i) => `- ${q}`).join('\n')}
-```
+// Launch parallel explorations for each selected perspective
+selectedPerspectives.forEach(perspective => {
+  Task({
+    subagent_type: "cli-explore-agent",
+    run_in_background: false,  // Sequential execution, wait for each
+    description: `Explore ${perspective.name}: ${topicSlug}`,
+    prompt: `
+## Analysis Context
+Topic: ${topic_or_question}
+Perspective: ${perspective.name} - ${perspective.focus}
+Session: ${sessionFolder}
 
----
+## MANDATORY FIRST STEPS
+1. Run: ccw tool exec get_modules_by_depth '{}'
+2. Execute searches focused on ${perspective.focus}
+3. Read: .workflow/project-tech.json (if exists)
 
-### Phase 3: Interactive Discussion (Multi-Round)
+## Exploration Focus (${perspective.name} angle)
+${perspective.exploration_tasks.map(t => `- ${t}`).join('\n')}
 
-**Step 3.1: Present Findings & Gather Feedback**
+## Output
+Write findings to: ${sessionFolder}/explorations/${perspective.name}.json
 
-```javascript
-// Maximum discussion rounds
-const MAX_ROUNDS = 5
-let roundNumber = 1
-let discussionComplete = false
-
-while (!discussionComplete && roundNumber <= MAX_ROUNDS) {
-  // Display current findings
-  console.log(`
-## Discussion Round ${roundNumber}
-
-${currentFindings}
-
-### Key Points for Your Input
-${discussionPoints.map((p, i) => `${i+1}. ${p}`).join('\n')}
-`)
-
-  // Gather user input
-  const userResponse = AskUserQuestion({
-    questions: [
-      {
-        question: "对以上分析有什么看法或补充?",
-        header: "Feedback",
-        multiSelect: false,
-        options: [
-          { label: "同意，继续深入", description: "分析方向正确，继续探索" },
-          { label: "需要调整方向", description: "我有不同的理解或重点" },
-          { label: "分析完成", description: "已获得足够信息" },
-          { label: "有具体问题", description: "我想问一些具体问题" }
-        ]
-      }
-    ]
+Schema: {relevant_files, patterns, key_findings, perspective_insights, _metadata}
+`
   })
-
-  // Process user response
-  switch (userResponse.feedback) {
-    case "同意，继续深入":
-      // Deepen analysis in current direction
-      await deepenAnalysis()
-      break
-    case "需要调整方向":
-      // Get user's adjusted focus
-      const adjustment = AskUserQuestion({
-        questions: [{
-          question: "请说明您希望调整的方向或重点:",
-          header: "Direction",
-          multiSelect: false,
-          options: [
-            { label: "更多代码细节", description: "深入代码实现" },
-            { label: "更多架构视角", description: "关注整体设计" },
-            { label: "更多实践对比", description: "对比最佳实践" }
-          ]
-        }]
-      })
-      await adjustAnalysisDirection(adjustment)
-      break
-    case "分析完成":
-      discussionComplete = true
-      break
-    case "有具体问题":
-      // Let user ask specific questions, then answer
-      await handleUserQuestions()
-      break
-  }
-
-  // Update discussion.md with this round
-  updateDiscussionDocument(roundNumber, userResponse, findings)
-  roundNumber++
-}
-```
-
-**Step 3.2: Document Each Round**
-
-Append to discussion.md:
-```markdown
-### Round ${n} - Discussion (${timestamp})
-
-#### User Input
-
-${userInputSummary}
-
-${userResponse === 'adjustment' ? `
-**Direction Adjustment**: ${adjustmentDetails}
-` : ''}
-
-${userResponse === 'questions' ? `
-**User Questions**:
-${userQuestions.map((q, i) => `${i+1}. ${q}`).join('\n')}
-
-**Answers**:
-${answers.map((a, i) => `${i+1}. ${a}`).join('\n')}
-` : ''}
-
-#### Updated Understanding
-
-Based on user feedback:
-- ${insight1}
-- ${insight2}
-
-#### Corrected Assumptions
-
-${corrections.length > 0 ? corrections.map(c => `
-- ~~${c.wrong}~~ → ${c.corrected}
-  - Reason: ${c.reason}
-`).join('\n') : 'None'}
-
-#### New Insights
-
-${newInsights.map(i => `- ${i}`).join('\n')}
+})
 ```
 
----
-
-### Phase 4: Synthesis & Conclusion
-
-**Step 4.1: Consolidate Insights**
+2. **Multi-Perspective CLI Analysis** (⚠️ AFTER exploration)
+   - If user selected multiple perspectives (≤4): Launch CLI calls in parallel
+   - If single/default perspective: Launch single comprehensive CLI analysis
+   - **Shared context**: Include exploration-codebase.json findings in all prompts
+   - **Execution**: Bash with run_in_background: true, wait for all results
+   - **Output**: perspectives.json with analysis from each perspective
 
+**Single Perspective Example**:
 ```javascript
-const conclusions = {
-  session_id: sessionId,
-  topic: topic_or_question,
-  completed: getUtc8ISOString(),
-  total_rounds: roundNumber,
-
-  summary: "...",
-
-  key_conclusions: [
-    { point: "...", evidence: "...", confidence: "high|medium|low" }
-  ],
-
-  recommendations: [
-    { action: "...", rationale: "...", priority: "high|medium|low" }
-  ],
-
-  open_questions: [...],
-
-  follow_up_suggestions: [
-    { type: "issue", summary: "..." },
-    { type: "task", summary: "..." }
-  ]
-}
-
-Write(conclusionsPath, JSON.stringify(conclusions, null, 2))
-```
-
-**Step 4.2: Final discussion.md Update**
-
-```markdown
----
-
-## Conclusions (${timestamp})
-
-### Summary
-
-${summaryParagraph}
-
-### Key Conclusions
-
-${conclusions.key_conclusions.map((c, i) => `
-${i+1}. **${c.point}** (Confidence: ${c.confidence})
-   - Evidence: ${c.evidence}
-`).join('\n')}
-
-### Recommendations
-
-${conclusions.recommendations.map((r, i) => `
-${i+1}. **${r.action}** (Priority: ${r.priority})
-   - Rationale: ${r.rationale}
-`).join('\n')}
-
-### Remaining Questions
-
-${conclusions.open_questions.map(q => `- ${q}`).join('\n')}
-
----
-
-## Current Understanding (Final)
-
-### What We Established
-
-${establishedPoints.map(p => `- ${p}`).join('\n')}
-
-### What Was Clarified/Corrected
-
-${corrections.map(c => `- ~~${c.original}~~ → ${c.corrected}`).join('\n')}
-
-### Key Insights
-
-${keyInsights.map(i => `- ${i}`).join('\n')}
-
----
-
-## Session Statistics
+Bash({
+  command: `ccw cli -p "
+PURPOSE: Analyze topic '${topic_or_question}' from ${dimensions.join(', ')} perspectives
+Success: Actionable insights with clear reasoning
 
-- **Total Rounds**: ${totalRounds}
-- **Duration**: ${duration}
-- **Sources Used**: ${sources.join(', ')}
-- **Artifacts Generated**: discussion.md, explorations.json, conclusions.json
-```
+PRIOR EXPLORATION CONTEXT:
+- Key files: ${explorationResults.relevant_files.slice(0,5).map(f => f.path).join(', ')}
+- Patterns found: ${explorationResults.patterns.slice(0,3).join(', ')}
+- Key findings: ${explorationResults.key_findings.slice(0,3).join(', ')}
 
-**Step 4.3: Post-Completion Options**
+TASK:
+• Build on exploration findings above
+• Analyze common patterns and anti-patterns
+• Highlight potential issues or opportunities
+• Generate discussion points for user clarification
 
-```javascript
-AskUserQuestion({
-  questions: [{
-    question: "分析完成。是否需要后续操作?",
-    header: "Next Steps",
-    multiSelect: true,
-    options: [
-      { label: "创建Issue", description: "将结论转为可执行的Issue" },
-      { label: "生成任务", description: "创建实施任务" },
-      { label: "导出报告", description: "生成独立的分析报告" },
-      { label: "完成", description: "不需要后续操作" }
-    ]
-  }]
+MODE: analysis
+CONTEXT: @**/* | Topic: ${topic_or_question}
+EXPECTED: Structured analysis with clear sections, specific insights tied to evidence, questions to deepen understanding, recommendations with rationale
+CONSTRAINTS: Focus on ${dimensions.join(', ')}
+" --tool gemini --mode analysis`,
+  run_in_background: true
 })
-
-// Handle selections
-if (selection.includes("创建Issue")) {
-  SlashCommand("/issue:new", `${topic_or_question} - 分析结论实施`)
-}
-if (selection.includes("生成任务")) {
-  SlashCommand("/workflow:lite-plan", `实施分析结论: ${summary}`)
-}
-if (selection.includes("导出报告")) {
-  exportAnalysisReport(sessionFolder)
-}
-```
-
----
-
-## Session Folder Structure
-
-```
-.workflow/.analysis/ANL-{slug}-{date}/
-├── discussion.md       # Evolution of understanding & discussions
-├── explorations.json   # CLI exploration findings
-├── conclusions.json    # Final synthesis
-└── exploration-*.json  # Individual exploration results (optional)
-```
-
-## Discussion Document Template
-
-```markdown
-# Analysis Discussion
-
-**Session ID**: ANL-xxx-2025-01-25
-**Topic**: [topic or question]
-**Started**: 2025-01-25T10:00:00+08:00
-**Dimensions**: [architecture, implementation, ...]
-
----
-
-## User Context
-
-**Focus Areas**: [user-selected focus]
-**Analysis Depth**: [quick|standard|deep]
-
----
-
-## Discussion Timeline
-
-### Round 1 - Initial Understanding (2025-01-25 10:00)
-
-#### Topic Analysis
-...
-
-#### Exploration Results
-...
-
-### Round 2 - Discussion (2025-01-25 10:15)
-
-#### User Input
-...
-
-#### Updated Understanding
-...
-
-#### Corrected Assumptions
-- ~~[wrong]~~ → [corrected]
-
-### Round 3 - Deep Dive (2025-01-25 10:30)
-...
-
----
-
-## Conclusions (2025-01-25 11:00)
-
-### Summary
-...
-
-### Key Conclusions
-...
-
-### Recommendations
-...
-
----
-
-## Current Understanding (Final)
-
-### What We Established
-- [confirmed points]
-
-### What Was Clarified/Corrected
-- ~~[original assumption]~~ → [corrected understanding]
-
-### Key Insights
-- [insights gained]
-
----
-
-## Session Statistics
-
-- **Total Rounds**: 3
-- **Duration**: 1 hour
-- **Sources Used**: codebase exploration, Gemini analysis
-- **Artifacts Generated**: discussion.md, explorations.json, conclusions.json
 ```
 
-## Iteration Flow
-
-```
-First Call (/workflow:analyze-with-file "topic"):
-   ├─ No session exists → New mode
-   ├─ Identify analysis dimensions
-   ├─ Scope with user (unless --yes)
-   ├─ Create discussion.md with initial understanding
-   ├─ Launch CLI explorations
-   └─ Enter discussion loop
-
-Continue Call (/workflow:analyze-with-file --continue "topic"):
-   ├─ Session exists → Continue mode
-   ├─ Load discussion.md
-   ├─ Resume from last round
-   └─ Continue discussion loop
-
-Discussion Loop:
-   ├─ Present current findings
-   ├─ Gather user feedback (AskUserQuestion)
-   ├─ Process response:
-   │   ├─ Agree → Deepen analysis
-   │   ├─ Adjust → Change direction
-   │   ├─ Question → Answer then continue
-   │   └─ Complete → Exit loop
-   ├─ Update discussion.md
-   └─ Repeat until complete or max rounds
-
-Completion:
-   ├─ Generate conclusions.json
-   ├─ Update discussion.md with final synthesis
-   └─ Offer follow-up options (issue, task, report)
-```
-
-## CLI Integration Points
-
-### 1. Codebase Exploration (cli-explore-agent)
-
-**Purpose**: Gather relevant code context
+**Multi-Perspective Example** (parallel, up to 4):
+```javascript
+// Build shared context once
+const explorationContext = `
+PRIOR EXPLORATION CONTEXT:
+- Key files: ${explorationResults.relevant_files.slice(0,5).map(f => f.path).join(', ')}
+- Patterns found: ${explorationResults.patterns.slice(0,3).join(', ')}
+- Key findings: ${explorationResults.key_findings.slice(0,3).join(', ')}`
+
+// Launch parallel CLI calls based on selected perspectives (max 4)
+selectedPerspectives.forEach(perspective => {
+  Bash({
+    command: `ccw cli -p "
+PURPOSE: ${perspective.purpose} for '${topic_or_question}'
+Success: ${perspective.success_criteria}
 
-**When**: Topic involves implementation or architecture analysis
+${explorationContext}
 
-### 2. Gemini Deep Analysis
+TASK:
+${perspective.tasks.map(t => `• ${t}`).join('\n')}
 
-**Purpose**: Conceptual analysis, pattern identification, best practices
+MODE: analysis
+CONTEXT: @**/* | Topic: ${topic_or_question}
+EXPECTED: ${perspective.expected_output}
+CONSTRAINTS: ${perspective.constraints}
+" --tool ${perspective.tool} --mode analysis`,
+    run_in_background: true
+  })
+})
 
-**Prompt Pattern**:
-```
-PURPOSE: Analyze topic + identify insights
-TASK: Explore dimensions + generate discussion points
-CONTEXT: Codebase + topic
-EXPECTED: Structured analysis + questions
+// ⚠️ STOP POINT: Wait for hook callback to receive all results before continuing
 ```
 
-### 3. Follow-up CLI Calls
+3. **Aggregate Findings**
+   - Consolidate all codebase explorations (exploration-codebase.json or explorations/*.json) and CLI perspective findings
+   - If multi-perspective: Extract synthesis from both explorations and analyses (convergent themes, conflicting views, unique contributions)
+   - Extract aggregated findings, discussion points, open questions across all sources
+   - Write to explorations.json (single) or perspectives.json (multi)
+
+4. **Update discussion.md**
+   - Append Round 1 section with exploration results
+   - Single perspective: Include sources analyzed, key findings, discussion points, open questions
+   - Multi-perspective: Include per-perspective findings + synthesis section
+
+**explorations.json Schema** (single perspective):
+- `session_id`: Session identifier
+- `timestamp`: Exploration completion time
+- `topic`: Original topic/question
+- `dimensions[]`: Analysis dimensions
+- `sources[]`: {type, file/summary}
+- `key_findings[]`: Main insights
+- `discussion_points[]`: Questions for user
+- `open_questions[]`: Unresolved questions
+
+**perspectives.json Schema** (multi-perspective):
+- `session_id`: Session identifier
+- `timestamp`: Exploration completion time
+- `topic`: Original topic/question
+- `dimensions[]`: Analysis dimensions
+- `perspectives[]`: [{name, tool, findings, insights, questions}]
+- `synthesis`: {convergent_themes, conflicting_views, unique_contributions}
+- `aggregated_findings[]`: Main insights across perspectives
+- `discussion_points[]`: Questions for user
+- `open_questions[]`: Unresolved questions
+
+**Success Criteria**:
+- exploration-codebase.json (single) or explorations/*.json (multi) created with codebase context
+- explorations.json (single) or perspectives.json (multi) created with findings
+- discussion.md updated with Round 1 results
+- All agents and CLI calls completed successfully
+- **📌 Key findings recorded** with evidence references and confidence levels
+- **📌 Exploration decisions recorded** (why chose certain perspectives, tool selection rationale)
+
+### Phase 3: Interactive Discussion
+
+**Objective**: Iteratively refine understanding through user-guided discussion cycles.
+
+**Prerequisites**:
+- Phase 2 completed successfully
+- explorations.json contains initial findings
+- discussion.md has Round 1 results
+
+**Guideline**: For complex tasks (code analysis, implementation, refactoring), delegate to agents via Task tool (cli-explore-agent, code-developer, universal-executor) or CLI calls (ccw cli). Avoid direct analysis/execution in main process.
+
+**Workflow Steps**:
+
+1. **Present Findings**
+   - Display current findings from explorations.json
+   - Show key points for user input
+
+2. **Gather User Feedback** (AskUserQuestion)
+   - **Question**: Feedback on current analysis
+   - **Options** (single-select):
+     - **同意，继续深入**: Analysis direction correct, deepen exploration
+     - **需要调整方向**: Different understanding or focus
+     - **分析完成**: Sufficient information obtained
+     - **有具体问题**: Specific questions to ask
+
+3. **Process User Response**
+
+   **📌 Recording Checkpoint**: Regardless of which option the user selects, the following MUST be recorded to discussion.md:
+   - User's original choice and expression
+   - Impact of this choice on analysis direction
+   - If direction changed, record a full Decision Record
+
+   **Agree, Deepen**:
+   - Continue analysis in current direction
+   - Use CLI for deeper exploration
+   - **📌 Record**: Which assumptions were confirmed, specific angles for deeper exploration
+
+   **Adjust Direction**:
+   - AskUserQuestion for adjusted focus (code details / architecture / best practices)
+   - Launch new CLI exploration with adjusted scope
+   - **📌 Record Decision**: Trigger reason for direction adjustment, old vs new direction comparison, expected impact
+
+   **Specific Questions**:
+   - Capture user questions
+   - Use CLI or direct analysis to answer
+   - Document Q&A in discussion.md
+   - **📌 Record**: Knowledge gaps revealed by the question, new understanding gained from the answer
+
+   **Complete**:
+   - Exit discussion loop, proceed to Phase 4
+   - **📌 Record**: Why concluding at this round (sufficient information / scope fully focused / user satisfied)
+
+4. **Update discussion.md**
+   - Append Round N section with:
+     - User input summary
+     - Direction adjustment (if any)
+     - User questions & answers (if any)
+     - Updated understanding
+     - Corrected assumptions
+     - New insights
+
+5. **📌 Intent Drift Check** (every round ≥ 2)
+   - Re-read "User Intent" from discussion.md header
+   - For each original intent item, check: addressed / in-progress / not yet discussed / implicitly absorbed
+   - If any item is "implicitly absorbed" (addressed by a different solution than originally envisioned), explicitly note this in discussion.md:
+     ```markdown
+     #### Intent Coverage Check
+     - ✅ Intent 1: [addressed in Round N]
+     - 🔄 Intent 2: [in-progress, current focus]
+     - ⚠️ Intent 3: [implicitly absorbed by X — needs explicit confirmation]
+     - ❌ Intent 4: [not yet discussed]
+     ```
+   - If any item is ❌ or ⚠️ after 3+ rounds, surface it to the user in the next round's presentation
+
+6. **Repeat or Converge**
+   - Continue loop (max 5 rounds) or exit to Phase 4
+
+**Discussion Actions**:
+
+| User Choice | Action | Tool | Description |
+|-------------|--------|------|-------------|
+| Deepen | Continue current direction | Gemini CLI | Deeper analysis in same focus |
+| Adjust | Change analysis angle | Selected CLI | New exploration with adjusted scope |
+| Questions | Answer specific questions | CLI or analysis | Address user inquiries |
+| Complete | Exit discussion loop | - | Proceed to synthesis |
+
+**Success Criteria**:
+- User feedback processed for each round
+- discussion.md updated with all discussion rounds
+- Assumptions corrected and documented
+- Exit condition reached (user selects "完成" or max rounds)
+- **📌 All decision points recorded** with Decision Record format
+- **📌 Direction changes documented** with before/after comparison and rationale
 
-**Purpose**: Deepen specific areas based on user feedback
-
-**Dynamic invocation** based on discussion direction
+### Phase 4: Synthesis & Conclusion
 
-## Consolidation Rules
+**Objective**: Consolidate insights, generate conclusions, offer next steps.
+
+**Prerequisites**:
+- Phase 3 completed successfully
+- Multiple rounds of discussion documented
+- User ready to conclude
+
+**Workflow Steps**:
+
+1. **📌 Intent Coverage Verification** (MANDATORY before synthesis)
+   - Re-read all original "User Intent" items from discussion.md header
+   - For EACH intent item, determine coverage status:
+     - **✅ Addressed**: Explicitly discussed and concluded with clear design/recommendation
+     - **🔀 Transformed**: Original intent evolved into a different solution — document the transformation chain
+     - **⚠️ Absorbed**: Implicitly covered by a broader solution — flag for explicit confirmation
+     - **❌ Missed**: Not discussed — MUST be either addressed now or explicitly listed as out-of-scope with reason
+   - Write "Intent Coverage Matrix" to discussion.md:
+     ```markdown
+     ### Intent Coverage Matrix
+     | # | Original Intent | Status | Where Addressed | Notes |
+     |---|----------------|--------|-----------------|-------|
+     | 1 | [intent text] | ✅ Addressed | Round N, Conclusion #M | |
+     | 2 | [intent text] | 🔀 Transformed | Round N → Round M | Original: X → Final: Y |
+     | 3 | [intent text] | ❌ Missed | — | Reason for omission |
+     ```
+   - **Gate**: If any item is ❌ Missed, MUST either:
+     - (a) Add a dedicated discussion round to address it before continuing, OR
+     - (b) Explicitly confirm with user that it is intentionally deferred
+   - Add `intent_coverage[]` to conclusions.json
+
+2. **Consolidate Insights**
+   - Extract all findings from discussion timeline
+   - **📌 Compile Decision Trail**: Aggregate all Decision Records from Phases 1-3 into a consolidated decision log
+   - **Key conclusions**: Main points with evidence and confidence levels (high/medium/low)
+   - **Recommendations**: Action items with rationale and priority (high/medium/low)
+   - **Open questions**: Remaining unresolved questions
+   - **Follow-up suggestions**: Issue/task creation suggestions
+   - **📌 Decision summary**: How key decisions shaped the final conclusions (link conclusions back to decisions)
+   - Write to conclusions.json
+
+2. **Final discussion.md Update**
+   - Append conclusions section:
+     - **Summary**: High-level overview
+     - **Key Conclusions**: Ranked with evidence and confidence
+     - **Recommendations**: Prioritized action items
+     - **Remaining Questions**: Unresolved items
+   - Update "Current Understanding (Final)":
+     - **What We Established**: Confirmed points
+     - **What Was Clarified/Corrected**: Important corrections
+     - **Key Insights**: Valuable learnings
+   - **📌 Add "Decision Trail" section**:
+     - **Critical Decisions**: List of pivotal decisions that shaped the analysis outcome
+     - **Direction Changes**: Timeline of scope/focus adjustments with rationale
+     - **Trade-offs Made**: Key trade-offs and why certain paths were chosen over others
+   - Add session statistics: rounds, duration, sources, artifacts, **decision count**
+
+3. **Post-Completion Options**
+
+   ```javascript
+   const hasActionableRecs = conclusions.recommendations?.some(r => r.priority === 'high' || r.priority === 'medium')
+
+   const nextStep = AskUserQuestion({
+     questions: [{
+       question: "Analysis complete. What's next?",
+       header: "Next Step",
+       multiSelect: false,
+       options: [
+         { label: hasActionableRecs ? "生成任务 (Recommended)" : "生成任务", description: "Launch workflow-lite-plan with analysis context" },
+         { label: "创建Issue", description: "Launch issue-discover with conclusions" },
+         { label: "导出报告", description: "Generate standalone analysis report" },
+         { label: "完成", description: "No further action" }
+       ]
+     }]
+   })
+   ```
+
+   **Handle "生成任务"**:
+   ```javascript
+   if (nextStep.includes("生成任务")) {
+     // 1. Build task description from high/medium priority recommendations
+     const taskDescription = conclusions.recommendations
+       .filter(r => r.priority === 'high' || r.priority === 'medium')
+       .map(r => r.action)
+       .join('\n') || conclusions.summary
+
+     // 2. Assemble compact analysis context as inline memory block
+     const contextLines = [
+       `## Prior Analysis (${sessionId})`,
+       `**Summary**: ${conclusions.summary}`
+     ]
+     const codebasePath = `${sessionFolder}/exploration-codebase.json`
+     if (file_exists(codebasePath)) {
+       const data = JSON.parse(Read(codebasePath))
+       const files = (data.relevant_files || []).slice(0, 8).map(f => f.path || f.file || f).filter(Boolean)
+       const findings = (data.key_findings || []).slice(0, 5)
+       if (files.length) contextLines.push(`**Key Files**: ${files.join(', ')}`)
+       if (findings.length) contextLines.push(`**Key Findings**:\n${findings.map(f => `- ${f}`).join('\n')}`)
+     }
+
+     // 3. Call lite-plan with enriched task description (no special flags)
+     Skill(skill="workflow-lite-plan", args=`"${taskDescription}\n\n${contextLines.join('\n')}"`)
+   }
+   ```
+
+**conclusions.json Schema**:
+- `session_id`: Session identifier
+- `topic`: Original topic/question
+- `completed`: Completion timestamp
+- `total_rounds`: Number of discussion rounds
+- `summary`: Executive summary
+- `key_conclusions[]`: {point, evidence, confidence}
+- `recommendations[]`: {action, rationale, priority}
+- `open_questions[]`: Unresolved questions
+- `follow_up_suggestions[]`: {type, summary}
+- `decision_trail[]`: {round, decision, context, options_considered, chosen, reason, impact}
+- `intent_coverage[]`: {intent, status, where_addressed, notes}
+
+**Success Criteria**:
+- conclusions.json created with final synthesis
+- discussion.md finalized with conclusions and decision trail
+- **📌 Intent Coverage Matrix** verified — all original intents accounted for (no ❌ Missed without explicit user deferral)
+- User offered next step options
+- Session complete
+- **📌 Complete decision trail** documented and traceable from initial scoping to final conclusions
+
+## Configuration
+
+### Analysis Perspectives
+
+Optional multi-perspective parallel exploration (single perspective is default, max 4):
+
+| Perspective | Tool | Focus | Best For |
+|------------|------|-------|----------|
+| **Technical** | Gemini | Implementation, code patterns, technical feasibility | Understanding how and technical details |
+| **Architectural** | Claude | System design, scalability, component interactions | Understanding structure and organization |
+| **Business** | Codex | Value, ROI, stakeholder impact, strategy | Understanding business implications |
+| **Domain Expert** | Gemini | Domain-specific patterns, best practices, standards | Industry-specific knowledge and practices |
+
+**Selection**: User can multi-select up to 4 perspectives in Phase 1, or default to single comprehensive view
+
+### Dimension-Direction Mapping
+
+When user selects focus areas, generate directions dynamically from detected dimensions (don't use static options):
+
+| Dimension | Possible Directions |
+|-----------|-------------------|
+| architecture | System Design, Component Interactions, Technology Choices, Integration Points, Design Patterns, Scalability Strategy |
+| implementation | Code Structure, Implementation Details, Code Patterns, Error Handling, Testing Approach, Algorithm Analysis |
+| performance | Performance Bottlenecks, Optimization Opportunities, Resource Utilization, Caching Strategy, Concurrency Issues |
+| security | Security Vulnerabilities, Authentication/Authorization, Access Control, Data Protection, Input Validation |
+| concept | Conceptual Foundation, Core Mechanisms, Fundamental Patterns, Theory & Principles, Trade-offs & Reasoning |
+| comparison | Solution Comparison, Pros & Cons Analysis, Technology Evaluation, Approach Differences |
+| decision | Decision Criteria, Trade-off Analysis, Risk Assessment, Impact Analysis, Implementation Implications |
+
+**Implementation**: Present 2-3 top dimension-related directions, allow user to multi-select and add custom directions.
+
+### Analysis Dimensions
+
+Dimensions matched against topic keywords to identify focus areas:
+
+| Dimension | Keywords |
+|-----------|----------|
+| architecture | 架构, architecture, design, structure, 设计 |
+| implementation | 实现, implement, code, coding, 代码 |
+| performance | 性能, performance, optimize, bottleneck, 优化 |
+| security | 安全, security, auth, permission, 权限 |
+| concept | 概念, concept, theory, principle, 原理 |
+| comparison | 比较, compare, vs, difference, 区别 |
+| decision | 决策, decision, choice, tradeoff, 选择 |
+
+### Consolidation Rules
 
 When updating "Current Understanding":
 
-1. **Promote confirmed insights**: Move validated findings to "What We Established"
-2. **Track corrections**: Keep important wrong→right transformations
-3. **Focus on current state**: What do we know NOW
-4. **Avoid timeline repetition**: Don't copy discussion details
-5. **Preserve key learnings**: Keep insights valuable for future reference
+| Rule | Description |
+|------|-------------|
+| Promote confirmed insights | Move validated findings to "What We Established" |
+| Track corrections | Keep important wrong→right transformations |
+| Focus on current state | What do we know NOW |
+| Avoid timeline repetition | Don't copy discussion details |
+| Preserve key learnings | Keep insights valuable for future reference |
 
-**Bad (cluttered)**:
+**Example**:
+
+❌ **Bad (cluttered)**:
 ```markdown
 ## Current Understanding
-
-In round 1 we discussed X, then in round 2 user said Y, and we explored Z...
+In round 1 we discussed X, then in round 2 user said Y...
 ```
 
-**Good (consolidated)**:
+✅ **Good (consolidated)**:
 ```markdown
 ## Current Understanding
 
@@ -769,36 +689,88 @@ In round 1 we discussed X, then in round 2 user said Y, and we explored Z...
 
 ### Key Insights
 - Current architecture supports horizontal scaling
-- Security audit recommended before production
 ```
 
 ## Error Handling
 
-| Situation | Action |
-|-----------|--------|
-| CLI exploration fails | Continue with available context, note limitation |
+| Error | Resolution |
+|-------|------------|
+| cli-explore-agent fails | Continue with available context, note limitation |
+| CLI timeout | Retry with shorter prompt, or skip perspective |
 | User timeout in discussion | Save state, show resume command |
 | Max rounds reached | Force synthesis, offer continuation option |
 | No relevant findings | Broaden search, ask user for clarification |
 | Session folder conflict | Append timestamp suffix |
 | Gemini unavailable | Fallback to Codex or manual analysis |
 
+## Best Practices
+
+1. **Clear Topic Definition**: Detailed topics lead to better dimension identification
+2. **Agent-First for Complex Tasks**: For code analysis, implementation, or refactoring tasks during discussion, delegate to agents via Task tool (cli-explore-agent, code-developer, universal-executor) or CLI calls (ccw cli). Avoid direct analysis/execution in main process
+3. **Review discussion.md**: Check understanding evolution before conclusions
+4. **Embrace Corrections**: Track wrong-to-right transformations as learnings
+5. **Document Evolution**: discussion.md captures full thinking process
+6. **Use Continue Mode**: Resume sessions to build on previous analysis
+7. **Record Decisions Immediately**: Never defer recording - capture decisions as they happen using the Decision Record format. A decision not recorded in-the-moment is a decision lost
+8. **Link Decisions to Outcomes**: When writing conclusions, explicitly reference which decisions led to which outcomes. This creates an auditable trail from initial scoping to final recommendations
+
+## Templates
+
+### Discussion Document Structure
+
+**discussion.md** contains:
+- **Header**: Session metadata (ID, topic, started, dimensions)
+- **User Context**: Focus areas, analysis depth
+- **Discussion Timeline**: Round-by-round findings
+  - Round 1: Initial Understanding + Exploration Results + **Initial Decision Log**
+  - Round 2-N: User feedback, adjusted understanding, corrections, new insights, **Decision Log per round**
+- **Decision Trail**: Consolidated critical decisions across all rounds
+- **Conclusions**: Summary, key conclusions, recommendations
+- **Current Understanding (Final)**: Consolidated insights
+- **Session Statistics**: Rounds, duration, sources, artifacts, decision count
+
+Example sections:
 
-## Usage Recommendations
+```markdown
+### Round 2 - Discussion (timestamp)
+
+#### User Input
+User agrees with current direction, wants deeper code analysis
+
+#### Decision Log
+> **Decision**: Shift focus from high-level architecture to implementation-level code analysis
+> - **Context**: User confirmed architectural understanding is sufficient
+> - **Options considered**: Continue architecture analysis / Deep-dive into code patterns / Focus on testing gaps
+> - **Chosen**: Deep-dive into code patterns — **Reason**: User explicitly requested code-level analysis
+> - **Impact**: Subsequent exploration will target specific modules rather than system overview
 
-Use `/workflow:analyze-with-file` when:
-- Exploring a complex topic collaboratively
-- Need documented discussion trail
-- Decision-making requires multiple perspectives
-- Want to iterate on understanding with user input
-- Building shared understanding before implementation
+#### Updated Understanding
+- Identified session management uses database-backed approach
+- Rate limiting applied at gateway, not application level
 
-Use `/workflow:debug-with-file` when:
-- Diagnosing specific bugs
-- Need hypothesis-driven investigation
-- Focus on evidence and verification
+#### Corrected Assumptions
+- ~~Assumed Redis for sessions~~ → Database-backed sessions
+  - Reason: User clarified architecture decision
 
-Use `/workflow:lite-plan` when:
+#### New Insights
+- Current design allows horizontal scaling without session affinity
+```
+
+## Usage Recommendations(Requires User Confirmation) 
+
+**When to Execute Directly :**
+- Short, focused analysis tasks (single module/component)
+- Clear, well-defined topics with limited scope
+- Quick information gathering without multi-round iteration
+- Follow-up analysis building on existing session
+
+**Use `Skill(skill="workflow-lite-plan", args="\"task description\"")` when:**
 - Ready to implement (past analysis phase)
-- Need structured task breakdown
-- Focus on execution planning
+- Need simple task breakdown
+- Focus on quick execution planning
+
+> **Note**: Phase 4「生成任务」assembles analysis context as inline `## Prior Analysis` block in task description, allowing lite-plan to skip redundant exploration automatically.
+
+---
+
+**Now execute analyze-with-file for**: $ARGUMENTS