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

description, argument-hint

description	argument-hint
Interactive collaborative analysis with documented discussions, CLI-assisted exploration, and evolving understanding	TOPIC="<topic or question to analyze>"

Codex Analyze-With-File Prompt

Overview

Interactive collaborative analysis workflow with documented discussion process. Records understanding evolution, facilitates multi-round Q&A, and uses deep analysis for codebase and concept 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
• Analysis-assisted exploration: Deep codebase and concept analysis
• Consolidated insights: Synthesizes discussions into actionable conclusions
• Flexible continuation: Resume analysis sessions to build on previous work

Target Topic

$TOPIC

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
   └─ Document initial understanding in discussion.md

Phase 2: Exploration (Parallel)
   ├─ Search codebase for relevant patterns
   ├─ Analyze code structure and dependencies
   └─ Aggregate findings into exploration summary

Phase 3: Interactive Discussion (Multi-Round)
   ├─ Present exploration findings
   ├─ Facilitate Q&A with user
   ├─ 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 (findings)
   └─ .workflow/.analysis/{slug}-{date}/conclusions.json (final synthesis)

Implementation Details

Session Setup & Mode Detection

const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()

const topicSlug = "$TOPIC".toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10)

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`

// Auto-detect mode
const sessionExists = fs.existsSync(sessionFolder)
const hasDiscussion = sessionExists && fs.existsSync(discussionPath)

const mode = hasDiscussion ? 'continue' : 'new'

if (!sessionExists) {
  bash(`mkdir -p ${sessionFolder}`)
}

---

Phase 1: Topic Understanding

Step 1.1: Parse Topic & Identify Dimensions

// 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")

Step 1.2: Initial Scoping (New Session Only)

Ask user to scope the analysis:

• Focus areas: 代码实现 / 架构设计 / 最佳实践 / 问题诊断
• Analysis depth: Quick Overview / Standard Analysis / Deep Dive

Step 1.3: Create/Update discussion.md

For new session:

# Analysis Discussion

**Session ID**: ${sessionId}
**Topic**: $TOPIC
**Started**: ${getUtc8ISOString()}
**Dimensions**: ${dimensions.join(', ')}

---

## User Context

**Focus Areas**: ${userFocusAreas.join(', ')}
**Analysis Depth**: ${analysisDepth}

---

## Discussion Timeline

### Round 1 - Initial Understanding (${timestamp})

#### Topic Analysis

Based on topic "$TOPIC":

- **Primary dimensions**: ${dimensions.join(', ')}
- **Initial scope**: ${initialScope}
- **Key questions to explore**:
  - ${question1}
  - ${question2}
  - ${question3}

#### Next Steps

- Search codebase for relevant patterns
- Gather insights via analysis
- Prepare discussion points for user

---

## Current Understanding

${initialUnderstanding}

For continue session, append:

### Round ${n} - Continuation (${timestamp})

#### Previous Context

Resuming analysis based on prior discussion.

#### New Focus

${newFocusFromUser}

---

Phase 2: Exploration

Step 2.1: Codebase Search

// Extract keywords from topic
const keywords = extractTopicKeywords("$TOPIC")

// Search codebase for relevant code
const searchResults = []
for (const keyword of keywords) {
  const results = Grep({ pattern: keyword, path: ".", output_mode: "content", "-C": 3 })
  searchResults.push({ keyword, results })
}

// Identify affected files and patterns
const relevantLocations = analyzeSearchResults(searchResults)

Step 2.2: Pattern Analysis

Analyze the codebase from identified dimensions:

1. Architecture patterns and structure
2. Implementation conventions
3. Dependency relationships
4. Potential issues or improvements

Step 2.3: Aggregate Findings

// Aggregate into explorations.json
const explorations = {
  session_id: sessionId,
  timestamp: getUtc8ISOString(),
  topic: "$TOPIC",
  dimensions: dimensions,
  sources: [
    { type: "codebase", summary: codebaseSummary },
    { type: "analysis", summary: analysisSummary }
  ],
  key_findings: [...],
  discussion_points: [...],
  open_questions: [...]
}

Write(explorationsPath, JSON.stringify(explorations, null, 2))

Step 2.4: Update discussion.md

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

---

Phase 3: Interactive Discussion (Multi-Round)

Step 3.1: Present Findings & Gather Feedback

// 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
  // Options:
  // - 同意，继续深入: Deepen analysis in current direction
  // - 需要调整方向: Get user's adjusted focus
  // - 分析完成: Exit loop
  // - 有具体问题: Answer specific questions

  // Process user response and update understanding
  updateDiscussionDocument(roundNumber, userResponse, findings)
  roundNumber++
}

Step 3.2: Document Each Round

Append to discussion.md:

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

const conclusions = {
  session_id: sessionId,
  topic: "$TOPIC",
  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

---

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

- **Total Rounds**: ${totalRounds}
- **Duration**: ${duration}
- **Sources Used**: ${sources.join(', ')}
- **Artifacts Generated**: discussion.md, explorations.json, conclusions.json

Step 4.3: Post-Completion Options

Offer follow-up options:

• Create Issue: Convert conclusions to actionable issues
• Generate Task: Create implementation tasks
• Export Report: Generate standalone analysis report
• Complete: No further action needed

---

Session Folder Structure

.workflow/.analysis/ANL-{slug}-{date}/
├── discussion.md       # Evolution of understanding & discussions
├── explorations.json   # Exploration findings
├── conclusions.json    # Final synthesis
└── exploration-*.json  # Individual exploration results (optional)

Discussion Document Template

# 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, analysis
- **Artifacts Generated**: discussion.md, explorations.json, conclusions.json

Iteration Flow

First Call (TOPIC="topic"):
   ├─ No session exists → New mode
   ├─ Identify analysis dimensions
   ├─ Scope with user
   ├─ Create discussion.md with initial understanding
   ├─ Launch explorations
   └─ Enter discussion loop

Continue Call (TOPIC="topic"):
   ├─ Session exists → Continue mode
   ├─ Load discussion.md
   ├─ Resume from last round
   └─ Continue discussion loop

Discussion Loop:
   ├─ Present current findings
   ├─ Gather user feedback
   ├─ 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

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

Bad (cluttered):

## Current Understanding

In round 1 we discussed X, then in round 2 user said Y, and we explored Z...

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
- Security audit recommended before production

Error Handling

Situation	Action
Exploration fails	Continue with available context, note limitation
User timeout in discussion	Save state, show resume instructions
Max rounds reached	Force synthesis, offer continuation option
No relevant findings	Broaden search, ask user for clarification
Session folder conflict	Append timestamp suffix

---

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