Claude-Code-Workflow/.claude/commands/workflow/analyze-with-file.md

---
name: analyze-with-file
description: Interactive collaborative analysis with documented discussions, CLI-assisted exploration, and evolving understanding
argument-hint: "[-y|--yes] [-c|--continue] \"topic or question\""
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
---

## Auto Mode

When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analysis angles.

# Workflow Analyze Command

## Quick Start

```bash
# Basic usage
/workflow:analyze-with-file "如何优化这个项目的认证架构"

# With options
/workflow:analyze-with-file --continue "认证架构"    # Continue existing session
/workflow:analyze-with-file -y "性能瓶颈分析"        # Auto mode
```

**Context Source**: cli-explore-agent + Gemini/Codex analysis
**Output Directory**: `.workflow/.analysis/{session-id}/`
**Core Innovation**: Documented discussion timeline with evolving understanding

## Output Artifacts

### Phase 1: Topic Understanding

| Artifact | Description |
|----------|-------------|
| `discussion.md` | Evolution of understanding & discussions (initialized) |
| Session variables | Dimensions, focus areas, analysis depth |

### Phase 2: CLI Exploration

| 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 |

### Phase 3: Interactive Discussion

| Artifact | Description |
|----------|-------------|
| Updated `discussion.md` | Round 2-N with user feedback and insights |
| Corrected assumptions | Tracked in discussion timeline |

### Phase 4: Synthesis & Conclusion

| Artifact | Description |
|----------|-------------|
| `conclusions.json` | Final synthesis with recommendations |
| Final `discussion.md` | ⭐ Complete analysis with conclusions |

## Overview

Interactive collaborative analysis workflow with **documented discussion process**. Records understanding evolution, facilitates multi-round Q&A, and uses CLI tools for deep exploration.

**Core workflow**: Topic → Explore → Discuss → Document → Refine → Conclude

```
┌─────────────────────────────────────────────────────────────────────────┐
│                    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)                       │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

## Output Structure

```
.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

### Session Initialization

**Objective**: Create session context and directory structure for 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}/`

**Session Variables**:
- `sessionId`: Unique session identifier
- `sessionFolder`: Base directory for all artifacts
- `autoMode`: Boolean for auto-confirmation
- `mode`: new | continue

### Phase 1: Topic Understanding

**Objective**: Analyze topic, identify dimensions, gather user input, initialize discussion.md.

**Prerequisites**:
- Session initialized with valid sessionId and sessionFolder
- Topic/question available from $ARGUMENTS

**Workflow Steps**:

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

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)

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

**Success Criteria**:
- Session folder created with discussion.md initialized
- Analysis dimensions identified
- User preferences captured (focus, depth)

### Phase 2: CLI Exploration

**Objective**: Gather codebase context, then execute deep analysis via CLI tools.

**Prerequisites**:
- Phase 1 completed successfully
- discussion.md initialized
- Dimensions identified

**Workflow Steps** (⚠️ Codebase exploration FIRST):

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
Task({
  subagent_type: "cli-explore-agent",
  run_in_background: false,
  description: `Explore codebase: ${topicSlug}`,
  prompt: `
## Analysis Context
Topic: ${topic_or_question}
Dimensions: ${dimensions.join(', ')}
Session: ${sessionFolder}

## MANDATORY FIRST STEPS
1. Run: ccw tool exec get_modules_by_depth '{}'
2. Execute relevant searches based on topic keywords
3. Read: .workflow/project-tech.json (if exists)

## Exploration Focus
${dimensions.map(d => `- ${d}: Identify relevant code patterns and structures`).join('\n')}

## Output
Write findings to: ${sessionFolder}/exploration-codebase.json

Schema: {relevant_files, patterns, key_findings, questions_for_user, _metadata}
`
})
```

**Multi-Perspective Parallel Example** (up to 4 agents):
```javascript
// 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)

## Exploration Focus (${perspective.name} angle)
${perspective.exploration_tasks.map(t => `- ${t}`).join('\n')}

## Output
Write findings to: ${sessionFolder}/explorations/${perspective.name}.json

Schema: {relevant_files, patterns, key_findings, perspective_insights, _metadata}
`
  })
})
```

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
Bash({
  command: `ccw cli -p "
PURPOSE: Analyze topic '${topic_or_question}' from ${dimensions.join(', ')} perspectives
Success: Actionable insights with clear reasoning

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(', ')}

TASK:
• Build on exploration findings above
• 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
})
```

**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}

${explorationContext}

TASK:
${perspective.tasks.map(t => `• ${t}`).join('\n')}

MODE: analysis
CONTEXT: @**/* | Topic: ${topic_or_question}
EXPECTED: ${perspective.expected_output}
CONSTRAINTS: ${perspective.constraints}
" --tool ${perspective.tool} --mode analysis`,
    run_in_background: true
  })
})

// ⚠️ STOP POINT: Wait for hook callback to receive all results before continuing
```

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

### 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**

   **Agree, Deepen**:
   - Continue analysis in current direction
   - Use CLI for deeper exploration

   **Adjust Direction**:
   - AskUserQuestion for adjusted focus (code details / architecture / best practices)
   - Launch new CLI exploration with adjusted scope

   **Specific Questions**:
   - Capture user questions
   - Use CLI or direct analysis to answer
   - Document Q&A in discussion.md

   **Complete**:
   - Exit discussion loop, proceed to Phase 4

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. **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)

### Phase 4: Synthesis & Conclusion

**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. **Consolidate Insights**
   - Extract all findings from discussion timeline
   - **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
   - 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 session statistics: rounds, duration, sources, artifacts

3. **Post-Completion Options** (AskUserQuestion)
   - **创建Issue**: Launch issue:new with conclusions
   - **生成任务**: Launch workflow:lite-plan for implementation
   - **导出报告**: Generate standalone analysis report
   - **完成**: No further action

**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}

**Success Criteria**:
- conclusions.json created with final synthesis
- discussion.md finalized with conclusions
- User offered next step options
- Session complete

## 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":

| 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 |

**Example**:

❌ **Bad (cluttered)**:
```markdown
## Current Understanding
In round 1 we discussed X, then in round 2 user said Y...
```

✅ **Good (consolidated)**:
```markdown
## Current Understanding

### What We Established
- The authentication flow uses JWT with refresh tokens
- Rate limiting is implemented at API gateway level

### What Was Clarified
- ~~Assumed Redis for sessions~~ → Actually uses database-backed sessions

### Key Insights
- Current architecture supports horizontal scaling
```

## Error Handling

| 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 → 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→right transformations as learnings
5. **Document Evolution**: discussion.md captures full thinking process
6. **Use Continue Mode**: Resume sessions to build on previous analysis

## 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
  - Round 2-N: User feedback, adjusted understanding, corrections, new insights
- **Conclusions**: Summary, key conclusions, recommendations
- **Current Understanding (Final)**: Consolidated insights
- **Session Statistics**: Rounds, duration, sources, artifacts

Example sections:

```markdown
### Round 2 - Discussion (timestamp)

#### User Input
User agrees with current direction, wants deeper code analysis

#### Updated Understanding
- Identified session management uses database-backed approach
- Rate limiting applied at gateway, not application level

#### Corrected Assumptions
- ~~Assumed Redis for sessions~~ → Database-backed sessions
  - Reason: User clarified architecture decision

#### 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:analyze-with-file", args="\"topic\"")` 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

**Use `Skill(skill="workflow:debug-with-file", args="\"bug description\"")` when:**
- Diagnosing specific bugs
- Need hypothesis-driven investigation
- Focus on evidence and verification

**Use `Skill(skill="workflow:brainstorm-with-file", args="\"topic or question\"")` when:**
- Generating new ideas or solutions
- Need creative exploration
- Want divergent thinking before convergence

**Use `Skill(skill="workflow:collaborative-plan-with-file", args="\"task description\"")` when:**
- Complex planning requiring multiple perspectives
- Large scope needing parallel sub-domain analysis
- Want shared collaborative planning document
- Need structured task breakdown with agent coordination

**Use `Skill(skill="workflow:lite-plan", args="\"task description\"")` when:**
- Ready to implement (past analysis phase)
- Need simple task breakdown
- Focus on quick execution planning

---

**Now execute analyze-with-file for**: $ARGUMENTS