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(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)

Auto Mode

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

Workflow Analyze Command

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	Artifact	Description
1	discussion.md	Evolution of understanding & discussions (initialized)
1	Session variables	Dimensions, focus areas, analysis depth
2	exploration-codebase.json	Single codebase context from cli-explore-agent
2	explorations/*.json	Multi-perspective codebase explorations (parallel, up to 4)
2	explorations.json	Single perspective aggregated findings
2	perspectives.json	Multi-perspective findings (up to 4) with synthesis
2	Updated discussion.md	Round 1 with exploration results
3	Updated discussion.md	Round 2-N with user feedback and insights
4	conclusions.json	Final synthesis with recommendations
4	Final discussion.md	Complete analysis with conclusions

Decision Recording Protocol

CRITICAL: Record immediately when any of these occur:

Trigger	What to Record	Target Section
Direction choice	What chosen, why, alternatives discarded	#### Decision Log
Key finding	Content, impact scope, confidence level	#### Key Findings
Assumption change	Old → new understanding, reason, impact	#### Corrected Assumptions
User feedback	Input, rationale for adoption/adjustment	#### User Input
Disagreement & trade-off	Conflicting views, trade-off basis, final choice	#### Decision Log
Scope adjustment	Before/after scope, trigger reason	#### Decision Log

Decision Record Format:

> **Decision**: [Description]
> - **Context**: [Trigger]
> - **Options considered**: [Alternatives]
> - **Chosen**: [Approach] — **Reason**: [Rationale]
> - **Impact**: [Effect on analysis]

Principles: Immediacy (record as-it-happens), Completeness (context+options+chosen+reason), Traceability (later phases trace back)

Implementation

Session Initialization

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 options: -c/--continue for continuation, -y/--yes for auto-approval
5. Auto-detect: If session folder + discussion.md exist → continue mode
6. Create directory structure

Session Variables: sessionId, sessionFolder, autoMode (boolean), mode (new|continue)

Phase 1: Topic Understanding

1. Parse Topic & Identify Dimensions — Match keywords against Analysis Dimensions table
2. Initial Scoping (if new session + not auto mode):
   • Focus: Multi-select from Dimension-Direction Mapping directions
   • Perspectives: Multi-select up to 4 (see Analysis Perspectives), default: single comprehensive
   • Depth: Quick Overview (10-15min) / Standard (30-60min) / Deep Dive (1-2hr)
3. Initialize discussion.md — Session metadata, user context, initial understanding, empty discussion timeline, initial dimension selection rationale
4. Record Phase 1 Decisions — Dimension selection reasoning, depth rationale, any user adjustments

Success: Session folder + discussion.md created, dimensions identified, preferences captured, decisions recorded

Phase 2: CLI Exploration

Codebase exploration FIRST, then CLI analysis.

Step 1: Codebase Exploration (cli-explore-agent, parallel up to 6)

• Single: General codebase analysis → {sessionFolder}/exploration-codebase.json
• Multi-perspective: Parallel per-perspective → {sessionFolder}/explorations/{perspective}.json
• Common tasks: ccw tool exec get_modules_by_depth '{}', keyword searches, read .workflow/project-tech.json

// Template for cli-explore-agent (single or per-perspective)
Agent({
  subagent_type: "cli-explore-agent",
  run_in_background: false,
  description: `Explore codebase: ${topicSlug}`,
  prompt: `
## Analysis Context
Topic: ${topic_or_question}
Dimensions: ${dimensions.join(', ')}
// For multi-perspective, add: Perspective: ${perspective.name} - ${perspective.focus}
Session: ${sessionFolder}

## MANDATORY FIRST STEPS
1. Run: ccw tool exec get_modules_by_depth '{}'
2. Read: .workflow/project-tech.json (if exists)

## Layered Exploration (MUST follow all 3 layers)

### Layer 1 — Module Discovery (Breadth)
- Search by topic keywords, identify ALL relevant files
- Map module boundaries and entry points → relevant_files[] with annotations

### Layer 2 — Structure Tracing (Depth)
- Top 3-5 key files: trace call chains 2-3 levels deep
- Identify data flow paths and dependencies → call_chains[], data_flows[]

### Layer 3 — Code Anchor Extraction (Detail)
- Each key finding: extract code snippet (20-50 lines) with file:line
- Annotate WHY this matters → code_anchors[]

## Output
Write to: ${sessionFolder}/exploration-codebase.json
// Multi-perspective: ${sessionFolder}/explorations/${perspective.name}.json

Schema: {relevant_files, patterns, key_findings, code_anchors: [{file, lines, snippet, significance}], call_chains: [{entry, chain, files}], questions_for_user, _metadata}
`
})

Step 2: CLI Analysis (AFTER exploration)

• Single: Comprehensive CLI analysis with exploration context
• Multi (up to 4): Parallel CLI calls per perspective
• Execution: Bash with run_in_background: true

// Build shared exploration context for CLI prompts
const explorationContext = `
PRIOR EXPLORATION CONTEXT:
- Key files: ${explorationResults.relevant_files.slice(0,5).map(f => f.path).join(', ')}
- Patterns: ${explorationResults.patterns.slice(0,3).join(', ')}
- Findings: ${explorationResults.key_findings.slice(0,3).join(', ')}
- Code anchors:
${(explorationResults.code_anchors || []).slice(0,5).map(a => `  [${a.file}:${a.lines}] ${a.significance}\n  \`\`\`\n  ${a.snippet}\n  \`\`\``).join('\n')}
- Call chains: ${(explorationResults.call_chains || []).slice(0,3).map(c => `${c.entry} → ${c.chain.join(' → ')}`).join('; ')}`

// Single perspective (for multi: loop selectedPerspectives with perspective.purpose/tasks/constraints)
Bash({
  command: `ccw cli -p "
PURPOSE: Analyze '${topic_or_question}' from ${dimensions.join(', ')} perspectives
Success: Actionable insights with clear reasoning

${explorationContext}

TASK:
• Build on exploration findings — reference specific code anchors
• Analyze common patterns and anti-patterns with code evidence
• Highlight potential issues/opportunities with file:line references
• Generate discussion points for user clarification

MODE: analysis
CONTEXT: @**/* | Topic: ${topic_or_question}
EXPECTED: Structured analysis with sections, insights tied to evidence, questions, recommendations
CONSTRAINTS: Focus on ${dimensions.join(', ')}
" --tool gemini --mode analysis`,
  run_in_background: true
})
// STOP: Wait for hook callback before continuing
// Multi-perspective: Same pattern per perspective with perspective.purpose/tasks/constraints/tool

Step 3: Aggregate Findings

• Consolidate explorations + CLI results
• Multi: Extract synthesis (convergent themes, conflicting views, unique contributions)
• Write to explorations.json (single) or perspectives.json (multi)

Step 4: Update discussion.md — Append Round 1 with sources, key findings, discussion points, open questions

explorations.json Schema (single):

• session_id, timestamp, topic, dimensions[]
• sources[]: {type, file/summary}
• key_findings[], code_anchors[]: {file, lines, snippet, significance}
• call_chains[]: {entry, chain, files}
• discussion_points[], open_questions[]

perspectives.json Schema (multi — extends explorations.json):

• perspectives[]: [{name, tool, findings, insights, questions}]
• synthesis: {convergent_themes, conflicting_views, unique_contributions}
• code_anchors/call_chains include perspective field

Success: Exploration + CLI artifacts created, discussion.md Round 1, key findings and exploration decisions recorded

Phase 3: Interactive Discussion

Guideline: Delegate complex tasks to agents (cli-explore-agent) or CLI calls. Avoid direct analysis in main process.

Loop (max 5 rounds):

1. Present Findings from explorations.json

2. Gather Feedback (AskUserQuestion, single-select):

   • 同意，继续深入: Direction correct, deepen
   • 需要调整方向: Different focus
   • 分析完成: Sufficient → exit to Phase 4
   • 有具体问题: Specific questions

3. Process Response (always record user choice + impact to discussion.md):

   Agree, Deepen → Dynamically generate deepen directions from current analysis context:

   • Extract 3-4 options from: unresolved questions in explorations.json, low-confidence findings, unexplored dimensions, user-highlighted areas
   • Each option specifies: label, description, tool (cli-explore-agent for code-level / Gemini CLI for pattern-level), scope
   • AskUserQuestion with generated options (single-select)
   • Execute selected direction via corresponding tool
   • Merge new code_anchors/call_chains into existing results
   • Record confirmed assumptions + deepen angle

   Adjust Direction → AskUserQuestion for new focus → new CLI exploration → Record Decision (old vs new direction, reason, impact)

   Specific Questions → Capture, answer via CLI/analysis, document Q&A → Record gaps revealed + new understanding

   Complete → Exit loop → Record why concluding

4. Update discussion.md — Append Round N: user input, direction adjustment, Q&A, updated understanding, corrections, new insights

5. Intent Drift Check (every round >= 2):

   • Re-read original "User Intent" from discussion.md header
   • Check each item: addressed / in-progress / implicitly absorbed / not yet discussed

   #### Intent Coverage Check
   - ✅ Intent 1: [addressed in Round N]
   - 🔄 Intent 2: [in-progress]
   - ⚠️ Intent 3: [implicitly absorbed by X — needs confirmation]
   - ❌ Intent 4: [not yet discussed]
   

   • If ❌ or ⚠️ after 3+ rounds → surface to user in next round

Success: All rounds documented, assumptions corrected, all decisions recorded, direction changes with before/after

Phase 4: Synthesis & Conclusion

1. Intent Coverage Verification (MANDATORY before synthesis):

   • Check each original intent: ✅ Addressed / 🔀 Transformed / ⚠️ Absorbed / ❌ Missed

   ### Intent Coverage Matrix
   | # | Original Intent | Status | Where Addressed | Notes |
   |---|----------------|--------|-----------------|-------|
   | 1 | [intent] | ✅ Addressed | Round N, Conclusion #M | |
   | 2 | [intent] | 🔀 Transformed | Round N → M | Original: X → Final: Y |
   | 3 | [intent] | ❌ Missed | — | Reason |
   

   • Gate: ❌ Missed items must be either (a) addressed in additional round or (b) confirmed deferred by user
   • Add intent_coverage[] to conclusions.json

2. Consolidate Insights:

   • Compile Decision Trail from all phases
   • Key conclusions with evidence + confidence (high/medium/low)
   • Recommendations with rationale + priority (high/medium/low)
   • Open questions, follow-up suggestions
   • Decision summary linking conclusions back to decisions
   • Write to conclusions.json

3. Final discussion.md Update:

   • Conclusions: Summary, ranked key conclusions, prioritized recommendations, remaining questions
   • Current Understanding (Final): What established, what clarified/corrected, key insights
   • Decision Trail: Critical decisions, direction changes timeline, trade-offs
   • Session statistics: rounds, duration, sources, artifacts, decision count

4. Display Conclusions Summary — Present to user:

   • Analysis Report: summary, key conclusions (numbered, with confidence), recommendations (numbered, with priority + rationale)
   • Open questions if any
   • Link to full report: {sessionFolder}/discussion.md

5. Post-Completion Options (TERMINAL — analyze-with-file ends after selection):

   WORKFLOW BOUNDARY: After selection, analyze-with-file is COMPLETE. If "执行任务" selected, workflow-lite-plan takes over exclusively.

   AskUserQuestion (single-select, header: "Next Step"):

   • 执行任务 (Recommended if high/medium priority recs exist): Launch workflow-lite-plan
   • 产出Issue: Convert recommendations to issues via /issue:new
   • 完成: No further action

   Handle "产出Issue":

   1. For each recommendation in conclusions.recommendations (priority high/medium):
      • Build issue JSON: {title, context: rec.action + rec.rationale, priority: rec.priority == 'high' ? 2 : 3, source: 'discovery', labels: dimensions}
      • Create via pipe: echo '<issue-json>' | ccw issue create
   2. Display created issue IDs with next step hint: /issue:plan <id>

   Handle "执行任务" (TERMINAL — analyze-with-file ends here, lite-plan takes over):

   1. Build taskDescription from high/medium priority recommendations (fallback: summary)
   2. Assemble context: ## Prior Analysis ({sessionId}) + summary + key files (up to 8) + key findings (up to 5) from exploration-codebase.json
   3. Output session termination boundary:

      ⛔ ANALYZE-WITH-FILE SESSION COMPLETE
      All Phase 1-4 are FINISHED. DO NOT reference analyze-with-file phase instructions beyond this point.
      

   4. Hand off: Skill(skill="workflow-lite-plan", args="{taskDescription}\n\n{contextLines}")
   5. Return — analyze-with-file terminates

conclusions.json Schema:

• session_id, topic, completed, total_rounds, summary
• key_conclusions[]: {point, evidence, confidence, code_anchor_refs[]}
• code_anchors[]: {file, lines, snippet, significance}
• recommendations[]: {action, rationale, priority}
• open_questions[], follow_up_suggestions[]: {type, summary}
• decision_trail[]: {round, decision, context, options_considered, chosen, reason, impact}
• intent_coverage[]: {intent, status, where_addressed, notes}

Success: conclusions.json created, discussion.md finalized, Intent Coverage Matrix verified, complete decision trail documented

Configuration

Analysis Perspectives

Perspective	Tool	Focus	Best For
Technical	Gemini	Implementation, code patterns, feasibility	How + technical details
Architectural	Claude	System design, scalability, interactions	Structure + organization
Business	Codex	Value, ROI, stakeholder impact	Business implications
Domain Expert	Gemini	Domain patterns, best practices, standards	Industry knowledge

User multi-selects up to 4 in Phase 1, default: single comprehensive view.

Dimension-Direction Mapping

Dimension	Possible Directions
architecture	System Design, Component Interactions, Technology Choices, Integration Points, Design Patterns, Scalability
implementation	Code Structure, Details, Patterns, Error Handling, Testing, Algorithm Analysis
performance	Bottlenecks, Optimization, Resource Utilization, Caching, Concurrency
security	Vulnerabilities, Auth, Access Control, Data Protection, Input Validation
concept	Foundation, Core Mechanisms, Patterns, Theory, Trade-offs
comparison	Solution Comparison, Pros/Cons, Technology Evaluation, Approach Differences
decision	Criteria, Trade-off Analysis, Risk Assessment, Impact, Implementation Implications

Present 2-3 top directions per dimension, allow multi-select + custom.

Analysis Dimensions

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

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

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	Save state, show resume command
Max rounds reached	Force synthesis, offer continuation
No relevant findings	Broaden search, ask user for clarification
Session folder conflict	Append timestamp suffix
Gemini unavailable	Fallback to Codex or manual analysis

Lite-plan handoff: Phase 4「执行任务」assembles analysis context as inline ## Prior Analysis block, allowing lite-plan to skip redundant exploration.

---

Now execute analyze-with-file for: $ARGUMENTS