Claude-Code-Workflow/.codex/prompts/analyze-with-file.md

name, description, argument-hint

name	description	argument-hint
analyze-with-file	Interactive collaborative analysis with documented discussions, CLI-assisted exploration, and evolving understanding. Serial analysis for Codex.	TOPIC="<question or topic>" [--focus=<area>] [--depth=quick|standard|deep] [--continue]

Codex Analyze-With-File Workflow

Quick Start

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

Overview

This workflow enables iterative exploration and refinement of complex topics through sequential phases:

1. Topic Understanding - Parse the topic and identify analysis dimensions
2. CLI Exploration - Gather codebase context and perform deep analysis via Gemini
3. Interactive Discussion - Multi-round Q&A with user feedback and direction adjustments
4. Synthesis & Conclusion - Consolidate insights and generate actionable recommendations

The key innovation is documented discussion timeline that captures the evolution of understanding across all phases, enabling users to track how insights develop and assumptions are corrected.

Analysis Flow

Session Detection
   ├─ Check if analysis session exists for topic
   ├─ EXISTS + discussion.md → Continue mode
   └─ NOT_FOUND → New session mode

Phase 1: Topic Understanding
   ├─ Parse topic/question
   ├─ Identify analysis dimensions (architecture, implementation, performance, security, concept, comparison, decision)
   ├─ Initial scoping with user (focus areas, analysis depth)
   └─ Initialize discussion.md

Phase 2: CLI Exploration (Serial Execution)
   ├─ Codebase context gathering (project structure, related files, constraints)
   ├─ Gemini CLI analysis (build on codebase findings)
   └─ Aggregate findings into explorations.json

Phase 3: Interactive Discussion (Multi-Round)
   ├─ Present exploration findings to user
   ├─ Gather user feedback (deepen, adjust direction, ask questions, complete)
   ├─ Execute targeted CLI analysis based on user direction
   ├─ Update discussion.md with each round
   └─ Repeat until clarity achieved (max 5 rounds)

Phase 4: Synthesis & Conclusion
   ├─ Consolidate all insights and discussion rounds
   ├─ Generate final conclusions with recommendations
   ├─ Update discussion.md with synthesis
   └─ Offer follow-up options (create issue, generate task, export report)

Output Structure

.workflow/.analysis/ANL-{slug}-{date}/
├── discussion.md                # ⭐ Evolution of understanding & discussions
├── exploration-codebase.json    # Phase 2: Codebase context and project structure
├── explorations.json            # Phase 2: CLI analysis findings aggregated
└── conclusions.json             # Phase 4: Final synthesis with recommendations

Output Artifacts

Phase 1: Topic Understanding

Artifact	Purpose
discussion.md	Initialized with session metadata and initial questions
Session variables	Topic slug, dimensions, focus areas, analysis depth

Phase 2: CLI Exploration

Artifact	Purpose
exploration-codebase.json	Codebase context: relevant files, patterns, constraints
explorations.json	CLI analysis findings: key findings, discussion points, open questions
Updated discussion.md	Round 1-2: Exploration results and initial analysis

Phase 3: Interactive Discussion

Artifact	Purpose
Updated discussion.md	Round N (3-5): User feedback, direction adjustments, corrected assumptions
CLI analysis results	Deepened analysis, adjusted perspective, or specific question answers

Phase 4: Synthesis & Conclusion

Artifact	Purpose
conclusions.json	Final synthesis: key conclusions, recommendations, open questions
Final discussion.md	Complete analysis timeline with conclusions and final understanding

---

Implementation Details

Session Initialization

The workflow automatically generates a unique session identifier and directory structure based on the topic and current date (UTC+8).

Session ID Format: ANL-{slug}-{date}

• slug: Lowercase alphanumeric + Chinese characters, max 40 chars (derived from topic)
• date: YYYY-MM-DD format (UTC+8)

Session Directory: .workflow/.analysis/{sessionId}/

Auto-Detection: If session folder exists with discussion.md, automatically enters continue mode. Otherwise, creates new session.

Session Variables:

• sessionId: Unique identifier
• sessionFolder: Base directory for artifacts
• mode: "new" or "continue"
• dimensions: Analysis focus areas
• focusAreas: User-selected focus areas
• analysisDepth: quick|standard|deep

---

Phase 1: Topic Understanding

Objective: Parse the topic, identify relevant analysis dimensions, scope the analysis with user input, and initialize the discussion document.

Step 1.1: Parse Topic & Identify Dimensions

The workflow analyzes the topic text against predefined analysis dimensions to determine relevant focus areas.

Analysis Dimensions and Keywords:

Dimension	Keywords
architecture	架构, architecture, design, structure, 设计, pattern
implementation	实现, implement, code, coding, 代码, logic
performance	性能, performance, optimize, bottleneck, 优化, speed
security	安全, security, auth, permission, 权限, vulnerability
concept	概念, concept, theory, principle, 原理, understand
comparison	比较, compare, vs, difference, 区别, versus
decision	决策, decision, choice, tradeoff, 选择, trade-off

Matching Logic: Compare topic text against keyword lists. If multiple dimensions match, include all. If none match, default to "architecture" and "implementation".

Step 1.2: Initial Scoping (New Session Only)

For new analysis sessions, gather user preferences before exploration:

Focus Areas (Multi-select):

• 代码实现 (Implementation details)
• 架构设计 (Architecture design)
• 最佳实践 (Best practices)
• 问题诊断 (Problem diagnosis)

Analysis Depth (Single-select):

• 快速概览 (Quick overview, 10-15 minutes)
• 标准分析 (Standard analysis, 30-60 minutes)
• 深度挖掘 (Deep dive, 1-2+ hours)

Step 1.3: Initialize discussion.md

Create the main discussion document with session metadata, context, and placeholder sections.

discussion.md Structure:

• Header: Session ID, topic, start time, identified dimensions
• Analysis Context: User-selected focus areas, depth level, scope
• Initial Questions: Key questions to guide the analysis
• Discussion Timeline: Round-by-round findings and insights
• Current Understanding: To be populated after exploration

Key Features:

• Serves as the primary artifact throughout the workflow
• Captures all rounds of discussion and findings
• Documents assumption corrections and insight evolution
• Enables session continuity across multiple interactions

Success Criteria:

• Session folder created successfully
• discussion.md initialized with all metadata
• Analysis dimensions identified
• User preferences captured

---

Phase 2: CLI Exploration

Objective: Gather codebase context and execute deep analysis via CLI tools to build understanding of the topic.

Execution Model: Sequential (serial) execution - gather codebase context first, then perform CLI analysis building on those findings.

Step 2.1: Codebase Context Gathering

Use built-in tools to understand the codebase structure and identify relevant code related to the topic.

Context Gathering Activities:

1. Get project structure - Execute ccw tool exec get_modules_by_depth '{}' to understand module organization
2. Search for related code - Use Grep/Glob to find files matching topic keywords
3. Read project tech context - Load .workflow/project-tech.json if available for constraints and integration points
4. Analyze patterns - Identify common code patterns and architecture decisions

exploration-codebase.json Structure:

• relevant_files[]: Files related to the topic with relevance indicators
• patterns[]: Common code patterns and architectural styles identified
• constraints[]: Project-level constraints that affect the analysis
• integration_points[]: Key integration points between modules
• _metadata: Timestamp and context information

Key Information to Capture:

• Top 5-10 most relevant files with brief descriptions
• Recurring patterns in code organization and naming
• Project constraints (frameworks, architectural styles, tech stack)
• Integration patterns between modules
• Existing solutions or similar implementations

Step 2.2: Gemini CLI Analysis

Execute a comprehensive CLI analysis building on the codebase context gathered in Step 2.1.

CLI Execution: Synchronous analysis via Gemini with mode=analysis

Prompt Structure:

• PURPOSE: Clear goal and success criteria for the analysis
• PRIOR CODEBASE CONTEXT: Incorporate findings from Step 2.1 (top files, patterns, constraints)
• TASK: Specific investigation steps (analyze patterns, identify issues, generate insights, create discussion points)
• MODE: analysis (read-only)
• CONTEXT: Full codebase context with topic reference
• EXPECTED: Structured output with evidence-based insights and confidence levels
• CONSTRAINTS: Focus dimensions, ignore test files

Analysis Output Should Include:

• Structured analysis organized by analysis dimensions
• Specific insights tied to evidence (file references)
• Questions to deepen understanding
• Recommendations with clear rationale
• Confidence levels (high/medium/low) for conclusions
• 3-5 key findings with supporting details

Execution Guideline: Wait for CLI analysis to complete before proceeding to aggregation.

Step 2.3: Aggregate Findings

Consolidate results from codebase context gathering and CLI analysis into a unified findings document.

explorations.json Structure:

• session_id: Reference to the analysis session
• timestamp: Completion time
• topic: Original topic/question
• dimensions[]: Identified analysis dimensions
• sources[]: List of information sources (codebase exploration, CLI analysis)
• key_findings[]: Main insights with evidence
• discussion_points[]: Questions to engage user
• open_questions[]: Unresolved or partially answered questions
• _metadata: Processing metadata

Aggregation Activities:

1. Extract key findings from CLI analysis output
2. Cross-reference with codebase context
3. Identify discussion points that benefit from user input
4. Note open questions for follow-up investigation
5. Organize findings by analysis dimension

Step 2.4: Update discussion.md

Append exploration results to the discussion timeline.

Round 1-2 Sections (Initial Understanding + Exploration Results):

• Codebase Findings: Top relevant files and identified patterns
• Analysis Results: Key findings, discussion points, recommendations
• Sources Analyzed: Files and code patterns examined

Documentation Standards:

• Include direct references to analyzed files (file:line format)
• List discussion points as questions or open items
• Highlight key conclusions with confidence indicators
• Note any constraints that affect the analysis

Success Criteria:

• exploration-codebase.json created with comprehensive context
• explorations.json created with aggregated findings
• discussion.md updated with Round 1-2 results
• All explorations completed successfully
• Ready for interactive discussion phase

---

Phase 3: Interactive Discussion

Objective: Iteratively refine understanding through multi-round user-guided discussion cycles.

Max Rounds: 5 discussion rounds (can exit earlier if user indicates analysis is complete)

Step 3.1: Present Findings & Gather Feedback

Display current understanding and exploration findings to the user.

Presentation Content:

• Current understanding summary
• Key findings from exploration
• Open questions or areas needing clarification
• Available action options

User Feedback Options (AskUserQuestion - single select):

Option	Purpose	Next Action
继续深入	Analysis direction is correct, deepen investigation	Execute deeper CLI analysis on same topic
调整方向	Different understanding or focus needed	Ask for adjusted focus, rerun CLI analysis
有具体问题	Specific questions to ask about the topic	Capture questions, use CLI to answer them
分析完成	Sufficient information obtained	Exit discussion loop, proceed to synthesis

Step 3.2: Deepen Analysis

When user selects "continue deepening", execute more detailed investigation in the same direction.

Deepening Strategy:

• Focus on previously identified findings
• Investigate edge cases and special scenarios
• Identify patterns not yet discussed
• Suggest implementation or improvement approaches
• Provide risk/impact assessments

CLI Execution: Synchronous analysis via Gemini with emphasis on elaboration and detail.

Analysis Scope:

• Expand on prior findings with more specifics
• Investigate corner cases and limitations
• Propose concrete improvement strategies
• Provide risk/impact ratings for findings
• Generate follow-up questions

Step 3.3: Adjust Direction

When user indicates a different focus is needed, shift the analysis angle.

Direction Adjustment Process:

1. Ask user for adjusted focus area (through AskUserQuestion)
2. Determine new analysis angle (different dimension or perspective)
3. Execute CLI analysis from new perspective
4. Compare new insights with prior analysis
5. Identify what was missed and why

CLI Execution: Synchronous analysis via Gemini with new perspective.

Analysis Scope:

• Analyze topic from different dimension or angle
• Identify gaps in prior analysis
• Generate insights specific to new focus
• Cross-reference with prior findings
• Suggest investigation paths forward

Step 3.4: Answer Specific Questions

When user has specific questions, address them directly.

Question Handling Process:

1. Capture user questions (through AskUserQuestion)
2. Use CLI analysis or direct investigation to answer
3. Provide evidence-based answers with supporting details
4. Offer related follow-up investigations

CLI Execution: Synchronous analysis via Gemini focused on specific questions.

Analysis Scope:

• Answer each question directly and clearly
• Provide evidence and examples
• Clarify ambiguous or complex points
• Suggest related investigation areas
• Rate confidence for each answer

Step 3.5: Document Each Round

Update discussion.md with results from each discussion round.

Round N Sections (Rounds 3-5):

Section	Content
User Direction	Action taken (deepen/adjust/questions) and focus area
Analysis Results	Key findings, insights, next steps
Insights	New learnings or clarifications from this round
Corrected Assumptions	Important wrong→right transformations with explanation
Open Items	Remaining questions or areas for future investigation

Documentation Standards:

• Clear timestamps for each round
• Evidence-based findings with file references
• Explicit tracking of assumption corrections
• Organized by analysis dimension
• Links between rounds showing understanding evolution

Consolidation Rules:

• Promote confirmed insights to "What We Established"
• Track important corrections as learnings
• Focus on current understanding, not timeline details
• Avoid repeating discussion details
• Highlight key insights for future reference

Success Criteria:

• User feedback processed for each round
• discussion.md updated with all rounds
• Assumptions documented and corrected
• Exit condition reached (user selects complete or max rounds reached)

---

Phase 4: Synthesis & Conclusion

Objective: Consolidate insights from all discussion rounds, generate final conclusions and recommendations, and offer next steps.

Step 4.1: Consolidate Insights

Extract and synthesize all findings from the discussion timeline into coherent conclusions and recommendations.

Consolidation Activities:

1. Review all discussion rounds and accumulated findings
2. Identify confirmed conclusions with evidence
3. Extract actionable recommendations with rationale
4. Note remaining open questions
5. Generate follow-up suggestions

conclusions.json Structure:

Field	Purpose
session_id	Reference to analysis session
topic	Original topic/question
completed	Completion timestamp
total_rounds	Number of discussion rounds
summary	Executive summary of analysis
key_conclusions[]	Main conclusions with evidence and confidence
recommendations[]	Actionable recommendations with rationale and priority
open_questions[]	Unresolved questions for future investigation
follow_up_suggestions[]	Suggested next steps (issue/task/research)

Key Conclusions Format:

• point: Clear statement of the conclusion
• evidence: Supporting evidence or code references
• confidence: high|medium|low confidence level

Recommendations Format:

• action: Specific recommended action
• rationale: Reasoning and benefits
• priority: high|medium|low priority

Step 4.2: Final discussion.md Update

Append conclusions section and finalize the understanding document.

Synthesis & Conclusions Section:

• Executive Summary: Overview of analysis findings
• Key Conclusions: Ranked by confidence level with supporting evidence
• Recommendations: Prioritized action items with rationale
• Remaining Open Questions: Unresolved items for future work

Current Understanding (Final) Section:

Subsection	Content
What We Established	Confirmed points and validated findings
What Was Clarified	Important corrections (wrong→right)
Key Insights	Valuable learnings for future reference

Session Statistics:

• Total discussion rounds completed
• Key findings identified
• Analysis dimensions covered
• Artifacts generated

Documentation Standards:

• Clear evidence for conclusions
• Actionable, specific recommendations
• Organized by priority and confidence
• Links to relevant code or discussions

Step 4.3: Post-Completion Options

Offer user follow-up actions based on analysis results.

Available Options (AskUserQuestion - multi-select):

Option	Purpose	Action
创建Issue	Create actionable issue from findings	Launch issue:new with conclusions summary
生成任务	Generate implementation task	Launch workflow:lite-plan for task breakdown
导出报告	Generate standalone analysis report	Create formatted report document
完成	No further action	End workflow

Success Criteria:

• conclusions.json created with complete synthesis
• discussion.md finalized with all conclusions
• User offered meaningful next step options
• Session complete and all artifacts available

---

Configuration

Analysis Dimensions Reference

Dimensions guide the scope and focus of analysis:

Dimension	Description	Best For
architecture	System design, component interactions, design patterns	Understanding structure and organization
implementation	Code patterns, implementation details, algorithms	Understanding how things work technically
performance	Bottlenecks, optimization opportunities, resource usage	Finding and fixing performance issues
security	Vulnerabilities, authentication, access control	Identifying and addressing security risks
concept	Foundational ideas, principles, theory	Understanding fundamental mechanisms
comparison	Comparing solutions, evaluating alternatives	Making informed technology or approach choices
decision	Trade-offs, impact analysis, decision rationale	Understanding why decisions were made

Analysis Depth Levels

Depth	Duration	Scope	Questions
Quick (快速概览)	10-15 min	Surface level understanding	3-5 key questions
Standard (标准分析)	30-60 min	Moderate depth with good coverage	5-8 key questions
Deep (深度挖掘)	1-2+ hours	Comprehensive detailed analysis	10+ key questions

Focus Areas

Common focus areas that guide the analysis direction:

Focus	Description
代码实现	Implementation details, code patterns, algorithms
架构设计	System design, component structure, design patterns
最佳实践	Industry standards, recommended approaches, patterns
问题诊断	Identifying root causes, finding issues, debugging

---

Error Handling & Recovery

Situation	Action	Recovery
CLI timeout	Retry with shorter, focused prompt	Skip analysis or reduce depth
No relevant findings	Broaden search keywords or adjust scope	Ask user for clarification
User disengaged	Summarize progress and offer break point	Save state for later continuation
Max rounds reached (5)	Force synthesis phase	Highlight remaining questions in conclusions
Session folder conflict	Append timestamp suffix to session ID	Create unique folder and continue

---

Iteration Patterns

First Analysis Session

User initiates: TOPIC="specific question"
   ├─ No session exists → New session mode
   ├─ Parse topic and identify dimensions
   ├─ Scope analysis with user (focus areas, depth)
   ├─ Create discussion.md
   ├─ Gather codebase context
   ├─ Execute Gemini CLI analysis
   ├─ Aggregate findings
   └─ Enter multi-round discussion loop

Continue Existing Session

User resumes: TOPIC="same topic" with --continue flag
   ├─ Session exists → Continue mode
   ├─ Load previous discussion.md
   ├─ Load explorations.json
   └─ Resume from last discussion round

Discussion Loop (Rounds 3-5)

Each round:
   ├─ Present current findings
   ├─ Gather user feedback
   ├─ Process response:
   │   ├─ Deepen → Deeper CLI analysis on same topic
   │   ├─ Adjust → New CLI analysis with adjusted focus
   │   ├─ Questions → CLI analysis answering specific questions
   │   └─ Complete → Exit loop for synthesis
   ├─ Update discussion.md
   └─ Repeat until user selects complete or max rounds reached

Completion Flow

Final synthesis:
   ├─ Consolidate all insights
   ├─ Generate conclusions.json
   ├─ Update discussion.md with final synthesis
   ├─ Offer follow-up options
   └─ Archive session artifacts

---

Best Practices

Before Starting Analysis

1. Clear Topic Definition: Detailed topics lead to better dimension identification
2. User Context: Understanding focus preferences helps scope the analysis
3. Scope Understanding: Being clear about depth expectations sets correct analysis intensity

During Analysis

1. Review Findings: Check exploration results before proceeding to discussion
2. Document Assumptions: Track what you think is true for correction later
3. Use Continue Mode: Resume sessions to build on previous findings rather than starting over
4. Embrace Corrections: Track wrong→right transformations as valuable learnings
5. Iterate Thoughtfully: Each discussion round should meaningfully refine understanding

Documentation Practices

1. Evidence-Based: Every conclusion should reference specific code or patterns
2. Confidence Levels: Indicate confidence (high/medium/low) for conclusions
3. Timeline Clarity: Use clear timestamps for traceability
4. Evolution Tracking: Document how understanding changed across rounds
5. Action Items: Generate specific, actionable recommendations

---

Templates & Examples

discussion.md Structure

The discussion.md file evolves through the analysis:

Header Section:

Session ID, topic, start time, identified dimensions

Context Section:

Focus areas selected by user, analysis depth, scope

Discussion Timeline:

Round 1: Initial understanding + exploration results
Round 2: Codebase findings + CLI analysis results
Round 3-5: User feedback + direction adjustments + new insights

Conclusions Section:

Executive summary, key conclusions, recommendations, open questions

Final Understanding Section:

What we established (confirmed points)
What was clarified (corrected assumptions)
Key insights (valuable learnings)

Round Documentation Pattern

Each discussion round follows a consistent structure:

• Round Header: Number, timestamp, and action taken
• User Input: What the user indicated they wanted to focus on
• Analysis Results: New findings from this round's analysis
• Insights: Key learnings and clarifications
• Corrected Assumptions: Any wrong→right transformations
• Next Steps: Suggested investigation paths

---

When to Use This Workflow

Use analyze-with-file when:

• Exploring complex topics collaboratively with documented trail
• Need multi-round iterative refinement of understanding
• Decision-making requires exploring multiple perspectives
• Building shared understanding before implementation
• Want to document how understanding evolved

Use direct execution when:

• Short, focused analysis tasks (single component)
• Clear, well-defined topics with limited scope
• Quick information gathering without iteration
• Quick follow-up to existing session

Consider alternatives when:

• Specific bug diagnosis needed → use workflow:debug-with-file
• Generating new ideas/solutions → use workflow:brainstorm-with-file
• Complex planning with parallel perspectives → use workflow:collaborative-plan-with-file
• Ready to implement → use workflow:lite-plan

---

Now execute the analyze-with-file workflow for topic: $TOPIC