Claude-Code-Workflow/.codex/skills/analyze-with-file/SKILL.md

name, description, argument-hint

name	description	argument-hint
analyze-with-file	Interactive collaborative analysis with documented discussions, inline exploration, and evolving understanding. Serial execution with no agent delegation.	TOPIC="<question or topic>" [--depth=quick|standard|deep] [--continue]

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](quick|standard|deep)/)
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. -->
- [Analysis Context](#analysis-context)
- [Current Understanding](#current-understanding)
- [Discussion Timeline](#discussion-timeline)
- [Decision Trail](#decision-trail)

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

1. Load context sources: Reuse in-memory artifacts or read from disk
2. Enrich recommendations: Resolve target files, generate implementation steps, build convergence criteria
3. Generate .task/*.json: Individual task files with full execution context
4. Pre-execution analysis: Dependency validation, file conflicts, topological sort
5. User confirmation: Present task list, allow adjustment
6. Serial execution: Execute each task following generated implementation steps
7. 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

1. 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

1. Clear Topic Definition: Detailed topics lead to better dimension identification
2. User Context: Understanding focus preferences helps scope the analysis
3. Perspective Selection: Choose 2-4 perspectives for complex topics, single for focused queries
4. 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
6. 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

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
6. Multi-Perspective Synthesis: When using multiple perspectives, document convergent/conflicting themes
7. 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