Codex Analyze-With-File Prompt
Overview
Interactive collaborative analysis workflow with documented discussion process. Records understanding evolution, facilitates multi-round Q&A, and uses inline search tools for deep exploration.
Core workflow: Topic → Explore → Discuss → Document → Refine → Conclude → (Optional) Quick Execute
Key features:
-
Documented discussion timeline: Captures understanding evolution across all phases
-
Decision recording at every critical point: Mandatory recording of key findings, direction changes, and trade-offs
-
Multi-perspective analysis: Supports up to 4 analysis perspectives (serial, inline)
-
Interactive discussion: Multi-round Q&A with user feedback and direction adjustments
-
Quick execute: Convert conclusions directly to executable tasks
Decision Recording Protocol
CRITICAL: During analysis, the following situations MUST trigger immediate recording to discussion.md:
Trigger What to Record Target Section
Direction choice What was chosen, why, what alternatives were discarded
Decision Log
Key finding Finding content, impact scope, confidence level, hypothesis impact
Key Findings
Assumption change Old assumption → new understanding, reason, impact
Corrected Assumptions
User feedback User's original input, rationale for adoption/adjustment
User Input
Disagreement & trade-off Conflicting viewpoints, trade-off basis, final choice
Decision Log
Scope adjustment Before/after scope, trigger reason
Decision Log
Decision Record Format:
Decision: [Description of the decision]
- Context: [What triggered this decision]
- Options considered: [Alternatives evaluated]
- Chosen: [Selected approach] — Reason: [Rationale]
- Rejected: [Why other options were discarded]
- Impact: [Effect on analysis direction/conclusions]
Key Finding Record Format:
Finding: [Content]
- Confidence: [High/Medium/Low] — Why: [Evidence basis]
- Hypothesis Impact: [Confirms/Refutes/Modifies] hypothesis "[name]"
- Scope: [What areas this affects]
Recording Principles:
-
Immediacy: Record decisions as they happen, not at the end of a phase
-
Completeness: Capture context, options, chosen approach, reason, and rejected alternatives
-
Traceability: Later phases must be able to trace back why a decision was made
-
Depth: Capture reasoning and hypothesis impact, not just outcomes
Auto Mode
When --yes or -y : Auto-confirm exploration decisions, use recommended analysis angles, skip interactive scoping.
Quick Start
Basic usage
/codex:analyze-with-file TOPIC="How to optimize this project's authentication architecture"
With depth selection
/codex:analyze-with-file TOPIC="Performance bottleneck analysis" --depth=deep
Continue existing session
/codex:analyze-with-file TOPIC="authentication architecture" --continue
Auto mode (skip confirmations)
/codex:analyze-with-file -y TOPIC="Caching strategy analysis"
Target Topic
$TOPIC
Analysis Flow
Step 0: Session Setup ├─ Parse topic, flags (--depth, --continue, -y) ├─ Generate session ID: ANL-{slug}-{date} └─ Create session folder (or detect existing → continue mode)
Step 1: Topic Understanding ├─ Parse topic, identify analysis dimensions ├─ Initial scoping with user (focus areas, perspectives, depth) └─ Initialize discussion.md
Step 2: Exploration (Inline, No Agents)
├─ Detect codebase → search relevant modules, patterns
│ ├─ Run ccw spec load --category exploration (if spec system available)
│ └─ Use Grep, Glob, Read, mcp__ace-tool__search_context
├─ Multi-perspective analysis (if selected, serial)
│ ├─ Single: Comprehensive analysis
│ └─ Multi (≤4): Serial per-perspective analysis with synthesis
├─ Aggregate findings → explorations.json / perspectives.json
├─ Update discussion.md with Round 1
│ ├─ Replace ## Current Understanding with initial findings
│ └─ Update ## Table of Contents
└─ Initial Intent Coverage Check (early drift detection)
Step 3: Interactive Discussion (Multi-Round, max 5) ├─ Current Understanding Summary (round ≥ 2, before findings) ├─ Present exploration findings ├─ Gather user feedback ├─ Process response: │ ├─ Deepen → context-driven + heuristic options → deeper inline analysis │ ├─ Agree & Suggest → user-directed exploration │ ├─ Adjust → new inline analysis with adjusted focus │ ├─ Questions → direct answers with evidence │ └─ Complete → exit loop for synthesis ├─ Update discussion.md: │ ├─ Append round details + Narrative Synthesis │ ├─ Replace ## Current Understanding with latest state │ └─ Update ## Table of Contents ├─ Intent Drift Check (round ≥ 2, building on Phase 2 initial check) └─ Repeat until user selects complete or max rounds
Step 4: Synthesis & Conclusion ├─ Intent Coverage Verification (mandatory gate) ├─ Consolidate all insights → conclusions.json (with steps[] per recommendation) ├─ Update discussion.md with final synthesis ├─ Interactive Recommendation Review (per-recommendation confirm/modify/reject) └─ Offer options: quick execute / create issue / generate task / export / done
Step 5: Execute (Optional - user selects, routes by complexity) ├─ Simple (≤2 recs): Direct inline execution → summary in discussion.md └─ Complex (≥3 recs): EXECUTE.md pipeline ├─ Enrich recommendations → generate .task/TASK-*.json ├─ Pre-execution analysis (dependencies, file conflicts, execution order) ├─ User confirmation ├─ Direct inline execution (Read/Edit/Write/Grep/Glob/Bash) ├─ Record events → execution-events.md, update execution.md └─ Report completion summary
Configuration
Flag Default Description
-y, --yes
false Auto-confirm all decisions
--continue
false Continue existing session
--depth
standard Analysis depth: quick / standard / deep
Session ID format: ANL-{slug}-{YYYY-MM-DD}
-
slug: lowercase, alphanumeric + CJK characters, max 40 chars
-
date: YYYY-MM-DD (UTC+8)
-
Auto-detect continue: session folder + discussion.md exists → continue mode
Implementation Details
Session Initialization
Step 0: Initialize Session
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
// Parse flags const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') const continueMode = $ARGUMENTS.includes('--continue') const depthMatch = $ARGUMENTS.match(/--depth=\s/) const analysisDepth = depthMatch ? depthMatch[1] : 'standard'
// Extract topic const topic = $ARGUMENTS.replace(/--yes|-y|--continue|--depth[=\s]\w+|TOPIC=/g, '').replace(/^["']|["']$/g, '').trim()
// Determine project root const projectRoot = Bash('git rev-parse --show-toplevel 2>/dev/null || pwd').trim()
const slug = topic.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-').substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10)
const sessionId = ANL-${slug}-${dateStr}
const sessionFolder = ${projectRoot}/.workflow/.analysis/${sessionId}
// Auto-detect continue: session folder + discussion.md exists → continue mode
// If continue → load discussion.md + explorations, resume from last round
Bash(mkdir -p ${sessionFolder})
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
Match topic keywords against analysis dimensions:
const ANALYSIS_DIMENSIONS = { 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'] }
// Match topic text against keyword lists // If multiple dimensions match, include all // If none match, default to "architecture" and "implementation" const dimensions = identifyDimensions(topic, ANALYSIS_DIMENSIONS)
Step 1.2: Initial Scoping (New Session Only)
For new sessions, gather user preferences (skipped in auto mode or continue mode):
if (!autoYes && !continueMode) { // 1. Focus areas (multi-select) // Generate directions dynamically from detected dimensions (see Dimension-Direction Mapping) const focusAreas = AskUserQuestion({ questions: [{ question: "Select analysis focus areas:", header: "Focus", multiSelect: true, options: generateFocusOptions(dimensions) // Dynamic based on dimensions }] })
// 2. Analysis perspectives (multi-select, max 4) const perspectives = AskUserQuestion({ questions: [{ question: "Select analysis perspectives (single = focused, multi = broader coverage):", header: "Perspectives", multiSelect: true, options: [ { label: "Technical", description: "Implementation patterns, code structure, technical feasibility" }, { label: "Architectural", description: "System design, scalability, component interactions" }, { label: "Security", description: "Vulnerabilities, authentication, access control" }, { label: "Performance", description: "Bottlenecks, optimization, resource utilization" } ] }] })
// 3. Analysis depth (single-select, unless --depth already set) // Quick: surface level | Standard: moderate depth | Deep: comprehensive }
Step 1.3: Initialize discussion.md
const discussionMd = `# Analysis Discussion
Session ID: ${sessionId} Topic: ${topic} Started: ${getUtc8ISOString()} Dimensions: ${dimensions.join(', ')} Depth: ${analysisDepth}
Table of Contents
<!-- TOC: Auto-updated after each round/phase. Links to major sections. -->
Current Understanding
<!-- REPLACEABLE BLOCK: Overwrite (not append) after each round with latest consolidated understanding. Follow Consolidation Rules: promote confirmed insights, track corrections, focus on current state. -->
To be populated after exploration.
Analysis Context
- Focus areas: ${focusAreas.join(', ')}
- Perspectives: ${selectedPerspectives.map(p => p.name).join(', ')}
- Depth: ${analysisDepth}
Initial Questions
${generateInitialQuestions(topic, dimensions).map(q => - ${q}).join('\n')}
Initial Decisions
Record why these dimensions and focus areas were selected.
Discussion Timeline
Rounds will be appended below as analysis progresses. Each round MUST include a Decision Log section for any decisions made.
Decision Trail
Consolidated critical decisions across all rounds (populated in Phase 4).
Write(${sessionFolder}/discussion.md`, discussionMd)
Success Criteria:
-
Session folder created with discussion.md initialized
-
Analysis dimensions identified
-
User preferences captured (focus, perspectives, depth)
-
Initial decisions recorded: Dimension selection rationale, excluded dimensions with reasons, user preference intent
Phase 2: Exploration
Objective: Gather codebase context and execute analysis to build understanding. All exploration done inline — no agent delegation.
Step 2.1: Detect Codebase & Explore
Search the codebase directly using available tools:
const hasCodebase = Bash( test -f package.json && echo "nodejs" || test -f go.mod && echo "golang" || test -f Cargo.toml && echo "rust" || test -f pyproject.toml && echo "python" || test -f pom.xml && echo "java" || test -d src && echo "generic" || echo "none").trim()
if (hasCodebase !== 'none') {
// 1. Read project metadata (if exists)
// - Run ccw spec load --category exploration (load project specs)
// - .workflow/specs/*.md (project conventions)
// 2. Search codebase for relevant content // Use: Grep, Glob, Read, or mcp__ace-tool__search_context // Search based on topic keywords and identified dimensions // Focus on: // - Modules/components related to the topic // - Existing patterns and code structure // - Integration points and constraints // - Relevant configuration and dependencies
// 3. Write findings
Write(${sessionFolder}/exploration-codebase.json, JSON.stringify({
project_type: hasCodebase,
relevant_files: [...], // [{path, relevance, summary}]
patterns: [...], // [{pattern, files, description}]
constraints: [...], // Architectural constraints found
integration_points: [...], // [{location, description}]
key_findings: [...], // Main insights from code search
_metadata: { timestamp: getUtc8ISOString(), exploration_scope: '...' }
}, null, 2))
}
Step 2.2: Multi-Perspective Analysis (if selected)
Analyze the topic from each selected perspective. All analysis done inline by the AI.
Single perspective (default):
// Analyze comprehensively across all identified dimensions // Use exploration-codebase.json as context // Focus on: patterns, anti-patterns, potential issues, opportunities
const findings = {
session_id: sessionId,
timestamp: getUtc8ISOString(),
topic: topic,
dimensions: dimensions,
sources: [...], // [{type, file, summary}]
key_findings: [...], // Main insights
discussion_points: [...], // Questions for user engagement
open_questions: [...] // Unresolved questions
}
Write(${sessionFolder}/explorations.json, JSON.stringify(findings, null, 2))
Multi-perspective (2-4 perspectives, serial):
// Analyze each perspective sequentially // For each perspective: // 1. Focus search/analysis on that perspective's concern area // 2. Generate perspective-specific insights // 3. Write individual findings
selectedPerspectives.forEach(perspective => {
// Analyze from this perspective's angle
// Use exploration-codebase.json + dimension focus
// Write to explorations/{perspective.name}.json
Write(${sessionFolder}/explorations/${perspective.name}.json, JSON.stringify({
perspective: perspective.name,
relevant_files: [...],
patterns: [...],
key_findings: [...],
perspective_insights: [...],
open_questions: [...],
_metadata: { timestamp: getUtc8ISOString() }
}, null, 2))
})
Step 2.3: Aggregate Findings
// Single perspective → explorations.json already written // Multi-perspective → synthesize into perspectives.json
if (selectedPerspectives.length > 1) { const synthesis = { session_id: sessionId, timestamp: getUtc8ISOString(), topic: topic, dimensions: dimensions,
// Individual perspective findings
perspectives: selectedPerspectives.map(p => ({
name: p.name,
findings: readJson(`${sessionFolder}/explorations/${p.name}.json`).key_findings,
insights: readJson(`${sessionFolder}/explorations/${p.name}.json`).perspective_insights,
questions: readJson(`${sessionFolder}/explorations/${p.name}.json`).open_questions
})),
// Cross-perspective synthesis
synthesis: {
convergent_themes: [...], // What all perspectives agree on
conflicting_views: [...], // Where perspectives differ
unique_contributions: [...] // Insights unique to specific perspectives
},
aggregated_findings: [...], // Main insights across all perspectives
discussion_points: [...], // Questions for user engagement
open_questions: [...] // Unresolved questions
}
Write(${sessionFolder}/perspectives.json, JSON.stringify(synthesis, null, 2))
}
Step 2.4: Update discussion.md
Append Round 1 with exploration results:
Single perspective round 1:
-
Sources analyzed (files, patterns)
-
Key findings with evidence
-
Discussion points for user
-
Open questions
Multi-perspective round 1:
-
Per-perspective summary (brief)
-
Synthesis section:
-
Convergent themes (what all perspectives agree on)
-
Conflicting views (where perspectives differ)
-
Unique contributions (insights from specific perspectives)
-
Discussion points
-
Open questions
Step 2.5: Initial Intent Coverage Check
Perform the FIRST intent coverage check before entering Phase 3:
// Re-read original user intent / analysis context from discussion.md header // Check each intent item against Round 1 findings // Append to discussion.md:
appendToDiscussion(`
Initial Intent Coverage Check (Post-Exploration)
${originalIntents.map((intent, i) => {
const status = assessCoverage(intent, explorationFindings)
return - ${status.icon} Intent ${i+1}: ${intent} — ${status.detail}
}).join('\n')}
接下来的讨论将重点关注未覆盖 (❌) 和进行中 (🔄) 的意图。 `)
// Present to user at beginning of Phase 3 for early course correction
Success Criteria:
-
exploration-codebase.json created with codebase context (if codebase exists)
-
explorations.json (single) or perspectives.json (multi) created with findings
-
discussion.md updated with Round 1 results
-
Initial Intent Coverage Check completed — early drift detection before interactive rounds
-
Ready for interactive discussion
-
Key findings recorded with evidence references and confidence levels
-
Exploration decisions recorded (why certain perspectives/search strategies were chosen)
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: Current Understanding Summary & Present Findings
Current Understanding Summary (Round >= 2, BEFORE presenting new findings):
-
Generate 1-2 sentence recap of established consensus and last round's direction
-
Example: "到目前为止，我们已确认 [established facts]。上一轮 [key action/direction]。现在，这是新一轮的发现："
-
Purpose: Reset context, prevent cognitive overload, make incremental progress visible
Display current understanding and gather user direction:
// Round >= 2: Display Current Understanding Summary first if (round >= 2) { // Generate 1-2 sentence recap from previous round's narrative synthesis // Display before presenting new findings }
// Display current findings summary from explorations.json or perspectives.json // Show key points, discussion points, open questions
if (!autoYes) {
const feedback = AskUserQuestion({
questions: [{
question: Analysis round ${round}: Feedback on current findings?,
header: "Direction",
multiSelect: false,
options: [
{ label: "Deepen", description: "Analysis direction is correct, investigate deeper" },
{ label: "Agree & Suggest", description: "Agree with direction, but have specific next step in mind" },
{ label: "Adjust Direction", description: "Different understanding or focus needed" },
{ label: "Specific Questions", description: "Have specific questions to ask" },
{ label: "Analysis Complete", description: "Sufficient information obtained, proceed to synthesis" }
]
}]
})
}
Step 3.2: Process User Response
Recording Checkpoint: Regardless of which option the user selects, the following MUST be recorded to discussion.md:
-
User's original choice and expression
-
Impact of this choice on analysis direction
-
If direction changed, record a full Decision Record
Deepen — continue analysis in current direction:
// Generate deepen direction options dynamically: // - 2-3 context-driven options from: unresolved questions, low-confidence findings, unexplored dimensions // - 1-2 heuristic options that break current frame: // e.g., "compare with best practices in [related domain]", // "analyze under extreme load scenarios", // "review from security audit perspective", // "explore simpler architectural alternatives" // AskUserQuestion with generated options (single-select) // Execute selected direction via inline search tools // Merge new findings into explorations.json // Record: Which assumptions were confirmed, specific angles for deeper exploration
Agree & Suggest — user provides specific next step:
// Ask user for their specific direction (free text input) const userSuggestion = AskUserQuestion({ questions: [{ question: "请描述您希望下一步深入的方向:", header: "Your Direction", multiSelect: false, options: [/* user will select "Other" to type free text */] }] }) // Execute user's specific direction via inline search tools // Record: User-driven exploration rationale and findings
Adjust Direction — new focus area:
// Ask user for adjusted focus const adjustedFocus = AskUserQuestion({ questions: [{ question: "What should the new analysis focus be?", header: "New Focus", multiSelect: false, options: [ { label: "Code Details", description: "Deeper into implementation specifics" }, { label: "Architecture", description: "Broader structural analysis" }, { label: "Best Practices", description: "Industry standards and recommendations" } ] }] })
// Analyze from adjusted perspective using inline search // Compare new insights with prior analysis // Identify what was missed and why // Update explorations.json with adjusted findings // Record Decision: Trigger reason for direction adjustment, old vs new direction, expected impact
Specific Questions — answer directly:
// Capture user questions via AskUserQuestion (text input) // Answer each question based on codebase search and analysis // Provide evidence and file references // Rate confidence for each answer (high/medium/low) // Document Q&A in discussion.md // Record: Knowledge gaps revealed by the question, new understanding from the answer
Analysis Complete — exit loop, proceed to Phase 4.
// Record: Why concluding at this round (sufficient information / scope fully focused / user satisfied)
Step 3.3: Document Each Round
Update discussion.md with results from each discussion round:
Append to Discussion Timeline:
Section Content
User Direction Action taken (deepen/adjust/suggest/questions) and focus area
Decision Log Decisions made this round using Decision Record format (with rejected alternatives)
Key Findings Findings using Key Finding Record format (with confidence + hypothesis impact)
Analysis Results Detailed insights, evidence with file references
Corrected Assumptions Important wrong→right transformations with explanation
Open Items Remaining questions or areas for future investigation
Narrative Synthesis Round-end summary connecting this round to overall understanding evolution
Replace (not append) these sections:
Section Update Rule
Current Understanding
Overwrite with latest consolidated understanding. Follow Consolidation Rules: promote confirmed insights, track corrections, focus on current state — NOT cumulative history
Table of Contents
Update links to include new Round N sections and any new headings
Round Narrative Synthesis (append after each round update):
Round N: Narrative Synthesis
起点: 基于上一轮的 [conclusions/questions]，本轮从 [starting point] 切入。 关键进展: [New findings] [confirmed/refuted/modified] 了之前关于 [hypothesis] 的理解。 决策影响: 用户选择 [feedback type]，导致分析方向 [adjusted/deepened/maintained]。 当前理解: 经过本轮，核心认知更新为 [updated understanding]。 遗留问题: [remaining questions driving next round]
Documentation Standards:
-
Clear timestamps for each round
-
Evidence-based findings with file references and confidence levels
-
Explicit tracking of assumption corrections
-
Organized by analysis dimension
-
Narrative synthesis linking rounds into coherent understanding evolution
Step 3.4: Intent Drift Check (every round ≥ 2, building on Phase 2 initial check)
Re-read "User Intent" / "Analysis Context" from discussion.md header. Compare against the Initial Intent Coverage Check from Phase 2. For each original intent item, check updated coverage status:
Intent Coverage Check
-
✅ Intent 1: [addressed in Round N]
-
🔄 Intent 2: [in-progress, current focus]
-
⚠️ Intent 3: [implicitly absorbed by X — needs explicit confirmation]
-
❌ Intent 4: [not yet discussed]
-
If any item is "implicitly absorbed" (⚠️), note it explicitly in discussion.md — absorbed ≠ addressed
-
If ❌ or ⚠️ items exist → proactively surface to user at start of next round: "以下原始意图尚未充分覆盖：[list]。是否需要调整优先级？"
Success Criteria:
-
User feedback processed for each round
-
discussion.md updated with all discussion rounds
-
Assumptions documented and corrected
-
Exit condition reached (user selects complete or max rounds)
-
All decision points recorded with Decision Record format
-
Direction changes documented with before/after comparison and rationale
Phase 4: Synthesis & Conclusion
Objective: Consolidate insights from all discussion rounds, generate conclusions and recommendations.
Step 4.0: Intent Coverage Verification (MANDATORY before synthesis)
Re-read all original user intent / analysis context items from discussion.md header. For EACH item, determine coverage status:
-
✅ Addressed: Explicitly discussed and concluded with clear design/recommendation
-
🔀 Transformed: Original intent evolved into a different solution — document the transformation chain
-
⚠️ Absorbed: Implicitly covered by a broader solution — flag for explicit confirmation
-
❌ Missed: Not discussed — MUST be either addressed now or explicitly listed as out-of-scope with reason
Write "Intent Coverage Matrix" to discussion.md:
Intent Coverage Matrix
| # | Original Intent | Status | Where Addressed | Notes |
|---|---|---|---|---|
| 1 | [intent text] | ✅ Addressed | Round N, Conclusion #M | |
| 2 | [intent text] | 🔀 Transformed | Round N → Round M | Original: X → Final: Y |
| 3 | [intent text] | ❌ Missed | — | Reason for omission |
Gate: If any item is ❌ Missed, MUST either:
-
(a) Add a dedicated discussion round to address it before continuing, OR
-
(b) Explicitly confirm with user that it is intentionally deferred
Step 4.1: Consolidate Insights
const conclusions = {
session_id: sessionId,
topic: topic,
completed: getUtc8ISOString(),
total_rounds: roundCount,
summary: '...', // Executive summary
key_conclusions: [ // Main conclusions
{ point: '...', evidence: '...', confidence: 'high|medium|low' }
],
recommendations: [ // Actionable recommendations
{
action: '...', // What to do (imperative verb + target)
rationale: '...', // Why this matters
priority: 'high|medium|low',
evidence_refs: ['file:line', ...], // Supporting evidence locations
steps: [ // Granular sub-steps for execution
{ description: '...', target: 'file/module', verification: 'how to verify done' }
],
review_status: 'accepted|modified|rejected|pending' // Set during Phase 4 review
}
],
open_questions: [...], // Unresolved questions
follow_up_suggestions: [ // Next steps
{ type: 'issue|task|research', summary: '...' }
],
decision_trail: [ // Consolidated decisions from all phases
{ round: 1, decision: '...', context: '...', options_considered: [...], chosen: '...', rejected_reasons: '...', reason: '...', impact: '...' }
],
narrative_trail: [ // From Step 3.3 Narrative Synthesis
{ round: 1, starting_point: '...', key_progress: '...', hypothesis_impact: '...', updated_understanding: '...', remaining_questions: '...' }
],
intent_coverage: [ // From Step 4.0
{ intent: '...', status: 'addressed|transformed|absorbed|missed', where_addressed: '...', notes: '...' }
]
}
Write(${sessionFolder}/conclusions.json, JSON.stringify(conclusions, null, 2))
Step 4.2: Final discussion.md Update
Append conclusions section and finalize:
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
Decision Trail Section:
Subsection Content
Critical Decisions Pivotal decisions that shaped the analysis outcome
Direction Changes Timeline of scope/focus adjustments with rationale
Trade-offs Made Key trade-offs and why certain paths were chosen
Session Statistics: Total discussion rounds, key findings count, dimensions covered, artifacts generated, decision count.
Step 4.3: Interactive Recommendation Review (skip in auto mode)
Walk through each recommendation one-by-one for user confirmation before proceeding:
// Order recommendations by priority: high → medium → low const sortedRecs = conclusions.recommendations.sort(byPriority)
for (const [index, rec] of sortedRecs.entries()) { // 1. Present recommendation details // Display: action, rationale, priority, steps[] (numbered sub-steps with target + verification)
// 2. Gather user review
const review = AskUserQuestion({
questions: [{
question: Recommendation #${index + 1}: "${rec.action}" (${rec.priority} priority, ${rec.steps.length} steps). Your decision:,
header: Rec #${index + 1},
multiSelect: false,
options: [
{ label: "Accept", description: "Accept this recommendation as-is" },
{ label: "Modify", description: "Adjust scope, steps, or priority" },
{ label: "Reject", description: "Remove this recommendation" },
{ label: "Accept All Remaining", description: "Skip review for remaining recommendations" }
]
}]
})
// 3. Process review decision // Accept → rec.review_status = "accepted" // Modify → gather modification via free text → update rec → rec.review_status = "modified" // Reject → gather reason → rec.review_status = "rejected" // Accept All Remaining → mark all remaining as "accepted", break loop
// 4. Record review decision to discussion.md Decision Log // 5. Update conclusions.json }
// Display review summary: // Accepted: N | Modified: N | Rejected: N // Only accepted/modified recommendations proceed to next step
Review Summary Format (append to discussion.md):
Recommendation Review Summary
| # | Action | Priority | Steps | Review Status | Notes |
|---|---|---|---|---|---|
| 1 | [action] | high | 3 | ✅ Accepted | |
| 2 | [action] | medium | 2 | ✏️ Modified | [modification notes] |
| 3 | [action] | low | 1 | ❌ Rejected | [reason] |
Step 4.4: Post-Completion Options
Complexity Assessment — determine whether .task/*.json generation is warranted:
// Assess recommendation complexity to decide available options const recs = conclusions.recommendations || [] const complexity = assessComplexity(recs)
function assessComplexity(recs) { if (recs.length === 0) return 'none' if (recs.length <= 2 && recs.every(r => r.priority === 'low')) return 'simple' if (recs.length >= 3 || recs.some(r => r.priority === 'high')) return 'complex' return 'moderate' // 1-2 medium-priority recommendations }
// Complexity → available options mapping: // none: Done | Create Issue | Export Report // simple: Done | Create Issue | Export Report (no task generation — overkill) // moderate: Done | Generate Task | Create Issue | Export Report // complex: Quick Execute | Generate Task | Create Issue | Export Report | Done
if (!autoYes) {
const options = buildOptionsForComplexity(complexity)
AskUserQuestion({
questions: [{
question: Analysis complete (${recs.length} recommendations, complexity: ${complexity}). Next step:,
header: "Next Step",
multiSelect: false,
options: options
}]
})
} else {
// Auto mode: generate .task/*.json only for moderate/complex, skip for simple/none
if (complexity === 'complex' || complexity === 'moderate') {
// → Phase 5 Step 5.1-5.2 (task generation only, no execution)
} else {
// → Done (conclusions.json is sufficient output)
}
}
Options by Complexity:
Complexity Available Options Rationale
none
Done, Create Issue, Export Report No actionable recommendations
simple
Done, Create Issue, Export Report 1-2 low-priority items don't warrant formal task JSON
moderate
Generate Task, Create Issue, Export Report, Done Task structure helpful but execution not urgent
complex
Quick Execute, Generate Task, Create Issue, Export Report, Done Full pipeline justified
Selection Action
Quick Execute Jump to Phase 5 (only reviewed recs with status accepted/modified)
Create Issue Skill(skill="issue:new", args="...") (only reviewed recs)
Generate Task Jump to Phase 5 Step 5.1-5.2 only (generate .task/*.json, no execution)
Export Report Copy discussion.md + conclusions.json to user-specified location
Done Display artifact paths, end
Success Criteria:
-
conclusions.json created with complete synthesis
-
discussion.md finalized with conclusions and decision trail
-
Intent Coverage Matrix verified — all original intents accounted for (no ❌ Missed without explicit user deferral)
-
User offered meaningful next step options
-
Complete decision trail documented and traceable from initial scoping to final conclusions
Phase 5: Execute (Optional)
Objective: Execute analysis recommendations — route by complexity.
Trigger: User selects "Quick Execute" in Phase 4. In auto mode, triggered only for moderate /complex recommendations.
Routing Logic:
complexity assessment (from Phase 4.3) ├─ simple/moderate (≤2 recommendations, clear changes) │ └─ Direct inline execution — no .task/*.json overhead └─ complex (≥3 recommendations, or high-priority with dependencies) └─ Route to EXECUTE.md — full pipeline (task generation → execution)
Step 5.1: Route by Complexity
const recs = conclusions.recommendations || []
if (recs.length >= 3 || recs.some(r => r.priority === 'high')) { // COMPLEX PATH → EXECUTE.md pipeline // Full specification: EXECUTE.md // Flow: load all context → generate .task/*.json → pre-execution analysis → serial execution → finalize } else { // SIMPLE PATH → direct inline execution (below) }
Step 5.2: Simple Path — Direct Inline Execution
For simple/moderate recommendations, execute directly without .task/*.json ceremony:
// For each recommendation: recs.forEach((rec, index) => { // 1. Locate relevant files from evidence_refs or codebase search const files = rec.evidence_refs ?.filter(ref => ref.includes(':')) .map(ref => ref.split(':')[0]) || []
// 2. Read each target file files.forEach(filePath => Read(filePath))
// 3. Apply changes based on rec.action + rec.rationale // Use Edit (preferred) for modifications, Write for new files
// 4. Log to discussion.md — append execution summary })
// Append execution summary to discussion.md appendToDiscussion(`
Quick Execution Summary
- Recommendations executed: ${recs.length}
- Completed: ${getUtc8ISOString()}
${recs.map((rec, i) => `### ${i+1}. ${rec.action}
- Status: completed/failed
- Rationale: ${rec.rationale}
- Evidence: ${rec.evidence_refs?.join(', ') || 'N/A'}
).join('\n')})
Simple path characteristics:
-
No .task/*.json generation
-
No execution.md / execution-events.md
-
Execution summary appended directly to discussion.md
-
Suitable for 1-2 clear, low-risk recommendations
Step 5.3: Complex Path — EXECUTE.md Pipeline
For complex recommendations, follow the full specification in EXECUTE.md :
-
Load context sources: Reuse in-memory artifacts or read from disk
-
Enrich recommendations: Resolve target files, generate implementation steps, build convergence criteria
-
Generate .task/*.json : Individual task files with full execution context
-
Pre-execution analysis: Dependency validation, file conflicts, topological sort
-
User confirmation: Present task list, allow adjustment
-
Serial execution: Execute each task following generated implementation steps
-
Finalize: Update task states, write execution artifacts
Full specification: EXECUTE.md
Success Criteria:
-
Simple path: recommendations executed, summary in discussion.md
-
Complex path: .task/*.json generated with quality validation, execution tracked via execution.md + execution-events.md
-
Execution route chosen correctly based on complexity assessment
Output Structure
{projectRoot}/.workflow/.analysis/ANL-{slug}-{date}/ ├── discussion.md # Evolution of understanding & discussions ├── exploration-codebase.json # Phase 2: Codebase context ├── explorations/ # Phase 2: Multi-perspective explorations (if selected) │ ├── technical.json │ ├── architectural.json │ └── ... ├── explorations.json # Phase 2: Single perspective aggregated findings ├── perspectives.json # Phase 2: Multi-perspective findings with synthesis └── conclusions.json # Phase 4: Final synthesis with recommendations
Phase 5 complex path adds .task/ , execution.md , execution-events.md — see EXECUTE.md for structure.
File Phase Description
discussion.md
1-4 Session metadata → discussion timeline → conclusions. Simple execution summary appended here.
exploration-codebase.json
2 Codebase context: relevant files, patterns, constraints
explorations/*.json
2 Per-perspective exploration results (multi only)
explorations.json
2 Single perspective aggregated findings
perspectives.json
2 Multi-perspective findings with cross-perspective synthesis
conclusions.json
4 Final synthesis: conclusions, recommendations, open questions
Analysis Dimensions Reference
Dimensions guide the scope and focus of analysis:
Dimension Keywords Description
architecture 架构, architecture, design, structure, 设计, pattern System design, component interactions, design patterns
implementation 实现, implement, code, coding, 代码, logic Code patterns, implementation details, algorithms
performance 性能, performance, optimize, bottleneck, 优化, speed Bottlenecks, optimization opportunities, resource usage
security 安全, security, auth, permission, 权限, vulnerability Vulnerabilities, authentication, access control
concept 概念, concept, theory, principle, 原理, understand Foundational ideas, principles, theory
comparison 比较, compare, vs, difference, 区别, versus Comparing solutions, evaluating alternatives
decision 决策, decision, choice, tradeoff, 选择, trade-off Trade-offs, impact analysis, decision rationale
Analysis Perspectives
Optional multi-perspective analysis (single perspective is default, max 4):
Perspective Focus Best For
Technical Implementation patterns, code structure, technical feasibility Understanding how and technical details
Architectural System design, scalability, component interactions Understanding structure and organization
Security Security patterns, vulnerabilities, access control Identifying security risks
Performance Bottlenecks, optimization, resource utilization Finding performance issues
Selection: User can multi-select up to 4 perspectives in Phase 1, or default to single comprehensive view.
Analysis Depth Levels
Depth Scope Description
Quick Surface level understanding Fast overview, minimal exploration
Standard Moderate depth with good coverage Balanced analysis (default)
Deep Comprehensive detailed analysis Thorough multi-round investigation
Dimension-Direction Mapping
When user selects focus areas, generate directions dynamically from detected dimensions:
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.
Consolidation Rules
When updating "Current Understanding" in discussion.md:
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, not the journey
Avoid timeline repetition Don't copy discussion details into consolidated section
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
Templates
discussion.md Structure
The discussion.md file evolves through the analysis:
-
Header: Session ID, topic, start time, identified dimensions
-
Analysis Context: Focus areas, perspectives, depth level
-
Initial Questions: Key questions to guide the analysis
-
Initial Decisions: Why these dimensions and focus areas were selected
-
Discussion Timeline: Round-by-round findings with narrative synthesis
-
Round 1: Initial Understanding + Exploration Results + Initial Decision Log + Narrative Synthesis
-
Round 2-N: Current Understanding Summary + User feedback + direction adjustments + new insights + Decision Log + Key Findings + Narrative Synthesis
-
Decision Trail: Consolidated critical decisions across all rounds
-
Synthesis & Conclusions: Summary, key conclusions, recommendations
-
Current Understanding (Final): Consolidated insights
-
Session Statistics: Rounds completed, findings count, artifacts generated, decision count
Round Documentation Pattern
Each discussion round follows a consistent structure:
Round N - [Deepen|Adjust|Suggest|Q&A] (timestamp)
User Input
What the user indicated they wanted to focus on
Decision Log
Decision: [Description of direction/scope/approach decision made this round]
- Context: [What triggered this decision]
- Options considered: [Alternatives evaluated]
- Chosen: [Selected approach] — Reason: [Rationale]
- Rejected: [Why other options were discarded]
- Impact: [Effect on analysis direction/conclusions]
Key Findings
Finding: [Content]
- Confidence: [High/Medium/Low] — Why: [Evidence basis]
- Hypothesis Impact: [Confirms/Refutes/Modifies] hypothesis "[name]"
- Scope: [What areas this affects]
Analysis Results
Detailed findings from this round's analysis
- Finding 1 (evidence: file:line)
- Finding 2 (evidence: file:line)
Corrected Assumptions
Previous assumption→ Corrected understanding- Reason: Why the assumption was wrong
Open Items
Remaining questions or areas for investigation
Narrative Synthesis
起点: 基于上一轮的 [conclusions/questions]，本轮从 [starting point] 切入。 关键进展: [New findings] [confirmed/refuted/modified] 了之前关于 [hypothesis] 的理解。 决策影响: 用户选择 [feedback type]，导致分析方向 [adjusted/deepened/maintained]。 当前理解: 经过本轮，核心认知更新为 [updated understanding]。 遗留问题: [remaining questions driving next round]
Error Handling
Situation Action Recovery
No codebase detected Normal flow, pure topic analysis Proceed without exploration-codebase.json
Codebase search fails Continue with available context Note limitation in discussion.md
No relevant findings Broaden search keywords Ask user for clarification
User timeout in discussion Save state, show resume command Use --continue to resume
Max rounds reached (5) Force synthesis phase Highlight remaining questions in conclusions
Session folder conflict Append timestamp suffix Create unique folder and continue
Quick execute: task fails Record failure, ask user Retry, skip, or abort (see EXECUTE.md)
Quick execute: verification fails Mark as unverified Note in events, manual check
Quick execute: no recommendations Cannot generate .task/*.json Inform user, suggest lite-plan
Quick execute: simple recommendations Complexity too low for .task/*.json Direct inline execution (no task generation)
Best Practices
Core Principles
- Explicit user confirmation required before code modifications: The analysis phase is strictly read-only. Any code changes (Phase 5 quick execute) require user approval.
Before Starting Analysis
-
Clear Topic Definition: Detailed topics lead to better dimension identification
-
User Context: Understanding focus preferences helps scope the analysis
-
Perspective Selection: Choose 2-4 perspectives for complex topics, single for focused queries
-
Scope Understanding: Being clear about depth expectations sets correct analysis intensity
During Analysis
-
Review Findings: Check exploration results before proceeding to discussion
-
Document Assumptions: Track what you think is true for correction later
-
Use Continue Mode: Resume sessions to build on previous findings rather than starting over
-
Embrace Corrections: Track wrong→right transformations as valuable learnings
-
Iterate Thoughtfully: Each discussion round should meaningfully refine understanding
-
Record Decisions Immediately: Never defer recording — capture decisions as they happen using the Decision Record format. A decision not recorded in-the-moment is a decision lost
Documentation Practices
-
Evidence-Based: Every conclusion should reference specific code or patterns
-
Confidence Levels: Indicate confidence (high/medium/low) for conclusions
-
Timeline Clarity: Use clear timestamps for traceability
-
Evolution Tracking: Document how understanding changed across rounds
-
Action Items: Generate specific, actionable recommendations
-
Multi-Perspective Synthesis: When using multiple perspectives, document convergent/conflicting themes
-
Link Decisions to Outcomes: When writing conclusions, explicitly reference which decisions led to which outcomes — this creates an auditable trail from initial scoping to final recommendations
When to Use
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 Quick Execute (Phase 5) when:
-
Analysis conclusions contain clear, actionable recommendations
-
Simple: 1-2 clear changes → direct inline execution (no .task/ overhead)
-
Complex: 3+ recommendations with dependencies → EXECUTE.md pipeline (.task/*.json → serial execution)
Consider alternatives when:
-
Specific bug diagnosis needed → use debug-with-file
-
Generating new ideas/solutions → use brainstorm-with-file
-
Complex planning with parallel perspectives → use collaborative-plan-with-file
-
Ready to implement → use lite-plan
-
Requirement decomposition needed → use req-plan-with-file
Now execute the analyze-with-file workflow for topic: $TOPIC