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

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
analyze-with-file	Interactive collaborative analysis with documented discussions, CLI-assisted exploration, and evolving understanding	[-y|--yes] [-c|--continue] "topic or question"	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

# 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	Codebase context from cli-explore-agent
explorations.json	Aggregated CLI findings (Gemini/Codex)
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                                                │
│     ├─ cli-explore-agent: Codebase context (FIRST)                       │
│     ├─ Gemini/Codex: Deep analysis (AFTER exploration)                   │
│     ├─ 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: Codebase context
├── explorations.json          # Phase 2: Aggregated CLI findings
└── 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 code implementation, architecture design, best practices, problem diagnosis
   • 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:

1. Primary Codebase Exploration via cli-explore-agent (⚠️ FIRST)
   • Agent type: cli-explore-agent
   • Execution mode: synchronous (run_in_background: false)
   • Tasks:
     • Run: ccw tool exec get_modules_by_depth '{}'
     • Execute searches based on topic keywords
     • Read: .workflow/project-tech.json if exists
   • Output: {sessionFolder}/exploration-codebase.json
     • relevant_files: [{path, relevance, rationale}]
     • patterns: []
     • key_findings: []
     • questions_for_user: []
   • Purpose: Enrich CLI prompts with codebase context

Agent Call Example:

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": [{"path": "...", "relevance": "high|medium|low", "rationale": "..."}],
  "patterns": [],
  "key_findings": [],
  "questions_for_user": [],
  "_metadata": { "exploration_type": "codebase", "timestamp": "..." }
}
`
})

2. CLI Deep Analysis (⚠️ AFTER exploration)
   • Launch Gemini CLI with analysis mode
   • Shared context: Include exploration-codebase.json findings in prompt
   • Execution: Bash with run_in_background: true, wait for results
   • Output: Analysis findings with insights and discussion points

CLI Call Example:

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

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

3. Aggregate Findings

   • Consolidate codebase and CLI findings
   • Extract key findings, discussion points, open questions
   • Write to explorations.json

4. Update discussion.md

   • Append Round 1 section with exploration results
   • Include sources analyzed, key findings, discussion points, open questions

explorations.json Schema:

• 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

Success Criteria:

• exploration-codebase.json created with codebase context
• explorations.json created with aggregated findings
• discussion.md updated with Round 1 results
• All 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

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

## Current Understanding
In round 1 we discussed X, then in round 2 user said Y...

✅ Good (consolidated):

## 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. Review discussion.md: Check understanding evolution before conclusions
3. Embrace Corrections: Track wrong→right transformations as learnings
4. Document Evolution: discussion.md captures full thinking process
5. 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:

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

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