analyze-with-file

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex Analyze-With-File Prompt

Codex Analyze-With-File 提示词

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

具备文档化讨论流程的交互式协作分析工作流。记录认知演进过程，支持多轮问答，并使用内联搜索工具进行深度探索。

核心工作流：主题 → 探索 → 讨论 → 文档记录 → 优化 → 总结 →（可选）快速执行

关键特性:

文档化讨论时间线：捕获所有阶段的认知演进过程
多视角分析：支持最多4种分析视角（串行、内联）
交互式讨论：结合用户反馈和方向调整的多轮问答
快速执行：将结论直接转换为可执行任务

Auto Mode

自动模式

When

--yes

-y

: Auto-confirm exploration decisions, use recommended analysis angles, skip interactive scoping.

当使用

--yes

或

-y

参数时：自动确认探索决策，使用推荐的分析角度，跳过交互式范围界定。

Quick Start

快速开始

bash

undefined

bash

undefined

Basic usage

基础用法

/codex:analyze-with-file TOPIC="How to optimize this project's authentication architecture"

/codex:analyze-with-file TOPIC="如何优化此项目的认证架构"

With depth selection

选择分析深度

/codex:analyze-with-file TOPIC="Performance bottleneck analysis" --depth=deep

/codex:analyze-with-file TOPIC="性能瓶颈分析" --depth=deep

Continue existing session

继续现有会话

/codex:analyze-with-file TOPIC="authentication architecture" --continue

/codex:analyze-with-file TOPIC="认证架构" --continue

Auto mode (skip confirmations)

自动模式（跳过确认步骤）

/codex:analyze-with-file -y TOPIC="Caching strategy analysis"

undefined

/codex:analyze-with-file -y TOPIC="缓存策略分析"

undefined

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
   │   ├─ Read project-tech.json / project-guidelines.json (if exists)
   │   └─ 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

Step 3: Interactive Discussion (Multi-Round, max 5)
   ├─ Present exploration findings
   ├─ Gather user feedback
   ├─ Process response:
   │   ├─ Deepen → deeper inline analysis in current direction
   │   ├─ Adjust → new inline analysis with adjusted focus
   │   ├─ Questions → direct answers with evidence
   │   └─ Complete → exit loop for synthesis
   ├─ Update discussion.md with each round
   └─ Repeat until user selects complete or max rounds

Step 4: Synthesis & Conclusion
   ├─ Consolidate all insights → conclusions.json
   ├─ Update discussion.md with final synthesis
   └─ Offer options: quick execute / create issue / generate task / export / done

Step 5: Quick Execute (Optional - user selects)
   ├─ Convert conclusions.recommendations → tasks.jsonl (unified JSONL with convergence)
   ├─ 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

步骤0：会话设置
   ├─ 解析主题、标志位（--depth, --continue, -y）
   ├─ 生成会话ID：ANL-{slug}-{date}
   └─ 创建会话文件夹（或检测现有文件夹 → 进入继续模式）

步骤1：主题理解
   ├─ 解析主题，识别分析维度
   ├─ 与用户进行初始范围界定（重点领域、视角、深度）
   └─ 初始化discussion.md

步骤2：探索（内联执行，无代理）
   ├─ 检测代码库 → 搜索相关模块、模式
   │   ├─ 读取project-tech.json / project-guidelines.json（如果存在）
   │   └─ 使用Grep、Glob、Read、mcp__ace-tool__search_context工具
   ├─ 多视角分析（如果已选择，串行执行）
   │   ├─ 单视角：全面分析
   │   └─ 多视角（≤4）：按视角串行分析并进行综合
   ├─ 汇总发现 → 存入explorations.json / perspectives.json
   └─ 在discussion.md中更新第一轮内容

步骤3：交互式讨论（多轮，最多5轮）
   ├─ 展示探索发现
   ├─ 收集用户反馈
   ├─ 处理响应：
   │   ├─ 深化 → 沿当前方向进行更深入的内联分析
   │   ├─ 调整 → 调整重点后进行新的内联分析
   │   ├─ 提问 → 结合证据直接作答
   │   └─ 完成 → 退出循环进入综合阶段
   ├─ 每轮讨论后更新discussion.md
   └─ 重复直到用户选择完成或达到最大轮次

步骤4：综合与总结
   ├─ 整合所有见解 → 存入conclusions.json
   ├─ 在discussion.md中更新最终综合内容
   └─ 提供选项：快速执行 / 创建Issue / 生成任务 / 导出报告 / 完成

步骤5：快速执行（可选）
   ├─ 将conclusions.recommendations转换为tasks.jsonl（带收敛条件的统一JSONL格式）
   ├─ 执行前分析（依赖项、文件冲突、执行顺序）
   ├─ 用户确认
   ├─ 直接内联执行（Read/Edit/Write/Grep/Glob/Bash）
   ├─ 记录事件 → 存入execution-events.md，更新execution.md
   └─ 报告执行完成摘要

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

标志位	默认值	描述
`-y, --yes`	false	自动确认所有决策
`--continue`	false	继续现有会话
`--depth`	standard	分析深度：quick / standard / deep

会话ID格式：

ANL-{slug}-{YYYY-MM-DD}

slug：小写字母、数字+中日韩字符，最多40个字符
date：YYYY-MM-DD（UTC+8时区）
自动检测继续模式：会话文件夹 + discussion.md存在 → 进入继续模式

Implementation Details

实现细节

Session Initialization

会话初始化

Step 0: Initialize Session

步骤0：初始化会话

javascript

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}`)

javascript

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

// 解析标志位
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'

// 提取主题
const topic = $ARGUMENTS.replace(/--yes|-y|--continue|--depth[=\s]\w+|TOPIC=/g, '').replace(/^["']|["']$/g, '').trim()

// 确定项目根目录
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}`

// 自动检测继续模式：会话文件夹 + discussion.md存在 → 进入继续模式
// 如果是继续模式 → 加载discussion.md + 探索结果，从上一轮恢复
Bash(`mkdir -p ${sessionFolder}`)

Phase 1: Topic Understanding

阶段1：主题理解

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

步骤1.1：解析主题并识别维度

Match topic keywords against analysis dimensions:

javascript

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)

将主题关键词与分析维度进行匹配：

javascript

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']
}

// 将主题文本与关键词列表匹配
// 如果匹配多个维度，全部包含
// 如果没有匹配项，默认使用"architecture"和"implementation"
const dimensions = identifyDimensions(topic, ANALYSIS_DIMENSIONS)

Step 1.2: Initial Scoping (New Session Only)

步骤1.2：初始范围界定（仅新会话）

For new sessions, gather user preferences (skipped in auto mode or continue mode):

javascript

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
}

对于新会话，收集用户偏好（自动模式或继续模式下跳过）：

javascript

if (!autoYes && !continueMode) {
  // 1. 重点领域（多选）
  // 根据检测到的维度动态生成方向（参考维度-方向映射）
  const focusAreas = AskUserQuestion({
    questions: [{
      question: "选择分析重点领域:",
      header: "重点",
      multiSelect: true,
      options: generateFocusOptions(dimensions) // 基于维度动态生成
    }]
  })

  // 2. 分析视角（多选，最多4个）
  const perspectives = AskUserQuestion({
    questions: [{
      question: "选择分析视角（单视角=聚焦，多视角=更广泛覆盖）:",
      header: "视角",
      multiSelect: true,
      options: [
        { label: "Technical", description: "实现模式、代码结构、技术可行性" },
        { label: "Architectural", description: "系统设计、可扩展性、组件交互" },
        { label: "Security", description: "漏洞、认证、访问控制" },
        { label: "Performance", description: "瓶颈、优化、资源利用率" }
      ]
    }]
  })

  // 3. 分析深度（单选，除非已设置--depth）
  // Quick：表层分析 | Standard：中等深度（默认） | Deep：全面分析
}

Step 1.3: Initialize discussion.md

步骤1.3：初始化discussion.md

javascript

const discussionMd = `# Analysis Discussion

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

javascript

const discussionMd = `# 分析讨论

**会话ID**: ${sessionId}
**主题**: ${topic}
**开始时间**: ${getUtc8ISOString()}
**分析维度**: ${dimensions.join(', ')}
**分析深度**: ${analysisDepth}

Analysis Context

分析上下文

Focus areas: ${focusAreas.join(', ')}
Perspectives: ${selectedPerspectives.map(p => p.name).join(', ')}
Depth: ${analysisDepth}

重点领域: ${focusAreas.join(', ')}
分析视角: ${selectedPerspectives.map(p => p.name).join(', ')}
分析深度: ${analysisDepth}

Initial Questions

初始问题

${generateInitialQuestions(topic, dimensions).map(q =>

- ${q}

).join('\n')}

${generateInitialQuestions(topic, dimensions).map(q =>

- ${q}

).join('\n')}

Discussion Timeline

讨论时间线

Rounds will be appended below as analysis progresses.

随着分析推进，后续轮次将追加至下方。

Current Understanding

当前认知

To be populated after exploration.
 Write(
${sessionFolder}/discussion.md`, discussionMd)


**Success Criteria**:
- Session folder created with discussion.md initialized
- Analysis dimensions identified
- User preferences captured (focus, perspectives, depth)

探索完成后将填充此部分。
 Write(
${sessionFolder}/discussion.md`, discussionMd)


**成功标准**:
- 已创建会话文件夹并初始化discussion.md
- 已识别分析维度
- 已捕获用户偏好（重点、视角、深度）

Phase 2: Exploration

阶段2：探索

Objective: Gather codebase context and execute analysis to build understanding. All exploration done inline — no agent delegation.

目标：收集代码库上下文并执行分析以建立认知。所有探索均内联完成 — 无代理委托。

Step 2.1: Detect Codebase & Explore

步骤2.1：检测代码库并探索

Search the codebase directly using available tools:

javascript

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)
  //    - .workflow/project-tech.json (tech stack info)
  //    - .workflow/project-guidelines.json (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))
}

使用可用工具直接搜索代码库：

javascript

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. 读取项目元数据（如果存在）
  //    - .workflow/project-tech.json（技术栈信息）
  //    - .workflow/project-guidelines.json（项目规范）

  // 2. 搜索代码库中的相关内容
  //    使用: Grep、Glob、Read或mcp__ace-tool__search_context
  //    基于主题关键词和已识别维度进行搜索
  //    重点关注:
  //      - 与主题相关的模块/组件
  //      - 现有模式和代码结构
  //      - 集成点和约束
  //      - 相关配置和依赖

  // 3. 写入发现结果
  Write(`${sessionFolder}/exploration-codebase.json`, JSON.stringify({
    project_type: hasCodebase,
    relevant_files: [...],    // [{path, relevance, summary}]
    patterns: [...],          // [{pattern, files, description}]
    constraints: [...],       // 发现的架构约束
    integration_points: [...], // [{location, description}]
    key_findings: [...],      // 代码搜索的主要见解
    _metadata: { timestamp: getUtc8ISOString(), exploration_scope: '...' }
  }, null, 2))
}

Step 2.2: Multi-Perspective Analysis (if selected)

步骤2.2：多视角分析（如果已选择）

Analyze the topic from each selected perspective. All analysis done inline by the AI.

Single perspective (default):

javascript

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

javascript

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

从每个已选视角分析主题。所有分析均由AI内联完成。

单视角（默认）:

javascript

// 跨所有已识别维度进行全面分析
// 使用exploration-codebase.json作为上下文
// 重点关注: 模式、反模式、潜在问题、改进机会

const findings = {
  session_id: sessionId,
  timestamp: getUtc8ISOString(),
  topic: topic,
  dimensions: dimensions,
  sources: [...],            // [{type, file, summary}]
  key_findings: [...],       // 主要见解
  discussion_points: [...],  // 用于用户互动的问题
  open_questions: [...]      // 未解决的问题
}
Write(`${sessionFolder}/explorations.json`, JSON.stringify(findings, null, 2))

多视角（2-4个视角，串行执行）:

javascript

// 按顺序分析每个视角
// 对于每个视角:
//   1. 聚焦该视角的关注领域进行搜索/分析
//   2. 生成视角专属见解
//   3. 写入单独的发现结果

selectedPerspectives.forEach(perspective => {
  // 从该视角的角度进行分析
  // 使用exploration-codebase.json + 维度重点
  // 写入至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

步骤2.3：汇总发现结果

javascript

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

javascript

// 单视角 → explorations.json已写入
// 多视角 → 综合结果存入perspectives.json

if (selectedPerspectives.length > 1) {
  const synthesis = {
    session_id: sessionId,
    timestamp: getUtc8ISOString(),
    topic: topic,
    dimensions: dimensions,

    // 各视角的单独发现结果
    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
    })),

    // 跨视角综合
    synthesis: {
      convergent_themes: [...],   // 所有视角达成共识的内容
      conflicting_views: [...],   // 视角存在分歧的内容
      unique_contributions: [...]  // 特定视角的独特见解
    },

    aggregated_findings: [...],   // 所有视角的主要见解汇总
    discussion_points: [...],     // 用于用户互动的问题
    open_questions: [...]         // 未解决的问题
  }
  Write(`${sessionFolder}/perspectives.json`, JSON.stringify(synthesis, null, 2))
}

Step 2.4: Update discussion.md

步骤2.4：更新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

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
Ready for interactive discussion

追加第一轮探索结果：

单视角第一轮:

已分析的来源（文件、模式）
带证据的关键发现
向用户提出的讨论点
未解决的问题

多视角第一轮:

各视角摘要（简要）
综合部分:
- 共识主题（所有视角达成一致的内容）
- 分歧观点（视角存在差异的内容）
- 独特贡献（特定视角的见解）
讨论点
未解决的问题

成功标准:

已创建exploration-codebase.json并写入代码库上下文（如果存在代码库）
已创建explorations.json（单视角）或perspectives.json（多视角）并写入发现结果
已更新discussion.md的第一轮内容
准备进入交互式讨论

Phase 3: Interactive Discussion

阶段3：交互式讨论

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)

目标：通过多轮用户引导的讨论周期，迭代优化认知。

最大轮次：5轮讨论（如果用户表示分析完成可提前退出）

Step 3.1: Present Findings & Gather Feedback

步骤3.1：展示发现结果并收集反馈

Display current understanding and gather user direction:

javascript

// 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: "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" }
      ]
    }]
  })
}

展示当前认知并收集用户方向：

javascript

// 从explorations.json或perspectives.json中展示当前发现结果摘要
// 显示关键点、讨论点、未解决的问题

if (!autoYes) {
  const feedback = AskUserQuestion({
    questions: [{
      question: `分析第${round}轮：对当前发现结果的反馈？`,
      header: "方向",
      multiSelect: false,
      options: [
        { label: "深化", description: "分析方向正确，进行更深入调查" },
        { label: "调整方向", description: "需要不同的理解或重点" },
        { label: "特定问题", description: "有具体问题需要提问" },
        { label: "分析完成", description: "已获取足够信息，进入综合阶段" }
      ]
    }]
  })
}

Step 3.2: Process User Response

步骤3.2：处理用户响应

Deepen — continue analysis in current direction:

javascript

// Deeper inline analysis using search tools
// Investigate edge cases, special scenarios
// Identify patterns not yet discussed
// Suggest improvement approaches
// Provide risk/impact assessments
// Update explorations.json with deepening findings

Adjust Direction — new focus area:

javascript

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

Specific Questions — answer directly:

javascript

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

Analysis Complete — exit loop, proceed to Phase 4.

深化 — 沿当前方向继续分析:

javascript

// 使用搜索工具进行更深入的内联分析
// 调查边缘情况、特殊场景
// 识别尚未讨论的模式
// 提出改进方案
// 提供风险/影响评估
// 在explorations.json中更新深化后的发现结果

调整方向 — 新的重点领域:

javascript

// 询问用户调整后的重点
const adjustedFocus = AskUserQuestion({
  questions: [{
    question: "新的分析重点应该是什么？",
    header: "新重点",
    multiSelect: false,
    options: [
      { label: "代码细节", description: "更深入的实现细节" },
      { label: "架构", description: "更广泛的结构分析" },
      { label: "最佳实践", description: "行业标准和建议" }
    ]
  }]
})

// 从调整后的视角进行内联搜索分析
// 将新见解与之前的分析进行比较
// 识别之前遗漏的内容及原因
// 在explorations.json中更新调整后的发现结果

特定问题 — 直接回答:

javascript

// 通过AskUserQuestion捕获用户问题（文本输入）
// 基于代码库搜索和分析回答每个问题
// 提供证据和文件引用
// 为每个答案标注置信度（高/中/低）
// 在discussion.md中记录问答内容

分析完成 — 退出循环，进入阶段4。

Step 3.3: Document Each Round

步骤3.3：记录每一轮讨论

Update discussion.md with results from each discussion round:

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

Documentation Standards:

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

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)

在discussion.md中更新每一轮讨论的结果：

部分	内容
用户方向	采取的行动（深化/调整/提问）和重点领域
分析结果	关键发现、见解、带文件引用的证据
见解	本轮分析的新认知或澄清内容
修正的假设	重要的错误→正确的转变及解释
未完成项	剩余的问题或未来需要调查的领域

文档标准:

每轮讨论使用清晰的时间戳
基于证据的发现结果并附带文件引用
明确记录假设的修正过程
按分析维度组织内容
各轮次之间建立链接以展示认知演进

成功标准:

已处理每一轮的用户反馈
已更新discussion.md的所有讨论轮次内容
已记录并修正假设
已达到退出条件（用户选择完成或达到最大轮次）

Phase 4: Synthesis & Conclusion

阶段4：综合与总结

Objective: Consolidate insights from all discussion rounds, generate conclusions and recommendations.

目标：整合所有讨论轮次的见解，生成结论和建议。

Step 4.1: Consolidate Insights

步骤4.1：整合见解

javascript

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: '...', rationale: '...', priority: 'high|medium|low' }
  ],
  open_questions: [...],             // Unresolved questions
  follow_up_suggestions: [           // Next steps
    { type: 'issue|task|research', summary: '...' }
  ]
}
Write(`${sessionFolder}/conclusions.json`, JSON.stringify(conclusions, null, 2))

javascript

const conclusions = {
  session_id: sessionId,
  topic: topic,
  completed: getUtc8ISOString(),
  total_rounds: roundCount,
  summary: '...',                    // 执行摘要
  key_conclusions: [                 // 主要结论
    { point: '...', evidence: '...', confidence: 'high|medium|low' }
  ],
  recommendations: [                 // 可执行建议
    { action: '...', rationale: '...', priority: 'high|medium|low' }
  ],
  open_questions: [...],             // 未解决的问题
  follow_up_suggestions: [           // 后续步骤
    { type: 'issue|task|research', summary: '...' }
  ]
}
Write(`${sessionFolder}/conclusions.json`, JSON.stringify(conclusions, null, 2))

Step 4.2: Final discussion.md Update

步骤4.2：最终更新discussion.md

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

Session Statistics: Total discussion rounds, key findings count, dimensions covered, artifacts generated.

追加结论部分并定稿：

综合与结论部分:

执行摘要：分析发现结果概述
主要结论：按置信度排序并附带支持证据
建议：按优先级排序的行动项及理由
剩余未解决问题：未来工作中需要处理的未解决项

当前认知（最终）部分:

子部分	内容
已确认内容	已验证的结论和发现结果
已澄清内容	重要的修正（~~错误→正确~~）
关键见解	对未来有参考价值的重要认知

会话统计：总讨论轮次、关键发现数量、覆盖的维度、生成的制品。

Step 4.3: Post-Completion Options

步骤4.3：完成后选项

javascript

if (!autoYes) {
  AskUserQuestion({
    questions: [{
      question: "Analysis complete. Next step:",
      header: "Next Step",
      multiSelect: false,
      options: [
        { label: "Quick Execute", description: "Convert recommendations to tasks and execute serially" },
        { label: "Create Issue", description: "Create GitHub Issue from conclusions" },
        { label: "Generate Task", description: "Launch lite-plan for implementation planning" },
        { label: "Export Report", description: "Generate standalone analysis report" },
        { label: "Done", description: "Save analysis only, no further action" }
      ]
    }]
  })
}

Selection	Action
Quick Execute	Jump to Phase 5
Create Issue	`Skill(skill="issue:new", args="...")`
Generate Task	`Skill(skill="workflow:lite-plan", args="...")`
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
User offered meaningful next step options

javascript

if (!autoYes) {
  AskUserQuestion({
    questions: [{
      question: "分析完成。下一步:",
      header: "下一步",
      multiSelect: false,
      options: [
        { label: "快速执行", description: "将建议转换为任务并串行执行" },
        { label: "创建Issue", description: "从结论创建GitHub Issue" },
        { label: "生成任务", description: "启动lite-plan进行实施规划" },
        { label: "导出报告", description: "生成独立的分析报告" },
        { label: "完成", description: "仅保存分析结果，不进行后续操作" }
      ]
    }]
  })
}

选择	操作
快速执行	跳至阶段5
创建Issue	`Skill(skill="issue:new", args="...")`
生成任务	`Skill(skill="workflow:lite-plan", args="...")`
导出报告	将discussion.md + conclusions.json复制到用户指定位置
完成	显示制品路径，结束流程

成功标准:

已创建conclusions.json并完成综合内容
已定稿discussion.md并添加结论
已为用户提供有意义的后续选项

Phase 5: Quick Execute (Optional)

阶段5：快速执行（可选）

Objective: Convert analysis conclusions into JSONL execution list with convergence criteria, then execute tasks directly inline.

Trigger: User selects "Quick Execute" in Phase 4.

Key Principle: No additional exploration — analysis phase has already collected all necessary context. No CLI delegation — execute directly using tools.

Flow:

conclusions.json → tasks.jsonl → User Confirmation → Direct Inline Execution → execution.md + execution-events.md

Full specification: See

EXECUTE.md

for detailed step-by-step implementation.

目标：将分析结论转换为带收敛条件的JSONL执行列表，然后直接内联执行任务。

触发条件：用户在阶段4中选择"快速执行"。

核心原则：无需额外探索 — 分析阶段已收集所有必要上下文。无CLI委托 — 直接使用工具执行。

流程：

conclusions.json → tasks.jsonl → 用户确认 → 直接内联执行 → execution.md + execution-events.md

完整规范：详细的分步实现请参考

EXECUTE.md

。

Step 5.1: Generate tasks.jsonl

步骤5.1：生成tasks.jsonl

Convert

conclusions.recommendations

into unified JSONL task format. Each line is a self-contained task with convergence criteria:

javascript

const conclusions = JSON.parse(Read(`${sessionFolder}/conclusions.json`))
const explorations = file_exists(`${sessionFolder}/explorations.json`)
  ? JSON.parse(Read(`${sessionFolder}/explorations.json`))
  : file_exists(`${sessionFolder}/perspectives.json`)
    ? JSON.parse(Read(`${sessionFolder}/perspectives.json`))
    : null

const tasks = conclusions.recommendations.map((rec, index) => ({
  id: `TASK-${String(index + 1).padStart(3, '0')}`,
  title: rec.action,
  description: rec.rationale,
  type: inferTaskType(rec),  // fix | refactor | feature | enhancement | testing
  priority: rec.priority,
  effort: inferEffort(rec),  // small | medium | large
  files: extractFilesFromEvidence(rec, explorations).map(f => ({
    path: f,
    action: 'modify'
  })),
  depends_on: [],
  convergence: {
    criteria: generateCriteria(rec),         // Testable conditions
    verification: generateVerification(rec), // Executable command or steps
    definition_of_done: generateDoD(rec)     // Business language
  },
  evidence: rec.evidence || [],
  source: {
    tool: 'analyze-with-file',
    session_id: sessionId,
    original_id: `TASK-${String(index + 1).padStart(3, '0')}`
  }
}))

// Validate convergence quality (same as req-plan-with-file)
// Write one task per line
Write(`${sessionFolder}/tasks.jsonl`, tasks.map(t => JSON.stringify(t)).join('\n'))

将

conclusions.recommendations

转换为统一的JSONL任务格式。每行是一个带收敛条件的独立任务：

javascript

const conclusions = JSON.parse(Read(`${sessionFolder}/conclusions.json`))
const explorations = file_exists(`${sessionFolder}/explorations.json`)
  ? JSON.parse(Read(`${sessionFolder}/explorations.json`))
  : file_exists(`${sessionFolder}/perspectives.json`)
    ? JSON.parse(Read(`${sessionFolder}/perspectives.json`))
    : null

const tasks = conclusions.recommendations.map((rec, index) => ({
  id: `TASK-${String(index + 1).padStart(3, '0')}`,
  title: rec.action,
  description: rec.rationale,
  type: inferTaskType(rec),  // fix | refactor | feature | enhancement | testing
  priority: rec.priority,
  effort: inferEffort(rec),  // small | medium | large
  files: extractFilesFromEvidence(rec, explorations).map(f => ({
    path: f,
    action: 'modify'
  })),
  depends_on: [],
  convergence: {
    criteria: generateCriteria(rec),         // 可测试条件
    verification: generateVerification(rec), // 可执行命令或步骤
    definition_of_done: generateDoD(rec)     // 业务语言描述的完成标准
  },
  evidence: rec.evidence || [],
  source: {
    tool: 'analyze-with-file',
    session_id: sessionId,
    original_id: `TASK-${String(index + 1).padStart(3, '0')}`
  }
}))

// 验证收敛条件质量（与req-plan-with-file相同）
// 每行写入一个任务
Write(`${sessionFolder}/tasks.jsonl`, tasks.map(t => JSON.stringify(t)).join('\n'))

Step 5.2: Pre-Execution Analysis

步骤5.2：执行前分析

Validate feasibility: dependency detection, circular dependency check (DFS), topological sort for execution order, file conflict analysis.

验证可行性：依赖项检测、循环依赖检查（DFS）、执行顺序拓扑排序、文件冲突分析。

Step 5.3: Initialize Execution Artifacts

步骤5.3：初始化执行制品

Create

execution.md

(overview with task table, pre-execution analysis, execution timeline placeholder) and

execution-events.md

(chronological event log header).

创建

execution.md

（含任务表、执行前分析、执行时间线占位符的概述）和

execution-events.md

（ chronological事件日志头）。

Step 5.4: User Confirmation

步骤5.4：用户确认

javascript

if (!autoYes) {
  AskUserQuestion({
    questions: [{
      question: `Execute ${tasks.length} tasks directly?\n\nExecution: Direct inline, serial`,
      header: "Confirm",
      multiSelect: false,
      options: [
        { label: "Start Execution", description: "Execute all tasks serially" },
        { label: "Adjust Tasks", description: "Modify, reorder, or remove tasks" },
        { label: "Cancel", description: "Cancel execution, keep tasks.jsonl" }
      ]
    }]
  })
}

javascript

if (!autoYes) {
  AskUserQuestion({
    questions: [{
      question: `直接执行${tasks.length}个任务？\n\n执行方式：直接内联，串行执行`,
      header: "确认",
      multiSelect: false,
      options: [
        { label: "开始执行", description: "串行执行所有任务" },
        { label: "调整任务", description: "修改、重新排序或移除任务" },
        { label: "取消", description: "取消执行，保留tasks.jsonl" }
      ]
    }]
  })
}

Step 5.5: Direct Inline Execution

步骤5.5：直接内联执行

Execute tasks one by one directly using tools (Read, Edit, Write, Grep, Glob, Bash). No CLI delegation.

For each task in execution order:

Check dependencies satisfied
Record START event to
```
execution-events.md
```
Execute: read files → analyze changes → apply modifications → verify convergence
Record COMPLETE/FAIL event with convergence verification checklist
Update
```
execution.md
```
task status
Auto-commit if enabled (conventional commit format)

使用工具（Read、Edit、Write、Grep、Glob、Bash）逐个执行任务。无CLI委托。

对于执行顺序中的每个任务：

检查依赖项是否已满足
在
```
execution-events.md
```
中记录START事件
执行：读取文件 → 分析变更 → 应用修改 → 验证收敛条件
记录COMPLETE/FAIL事件及收敛验证清单
更新
```
execution.md
```
的任务状态
如果启用自动提交，使用规范提交格式提交

Step 5.6: Finalize & Follow-up

步骤5.6：定稿与后续

Update
```
execution.md
```
with final summary (statistics, task results table)
Finalize
```
execution-events.md
```
with session footer
Update
```
tasks.jsonl
```
with
```
_execution
```
state per task

javascript

if (!autoYes) {
  AskUserQuestion({
    questions: [{
      question: `Execution complete: ${completedTasks.size}/${tasks.length} succeeded.\nNext step:`,
      header: "Post-Execute",
      multiSelect: false,
      options: [
        { label: "Retry Failed", description: `Re-execute ${failedTasks.size} failed tasks` },
        { label: "View Events", description: "Display execution-events.md" },
        { label: "Create Issue", description: "Create issue from failed tasks" },
        { label: "Done", description: "End workflow" }
      ]
    }]
  })
}

Success Criteria:

```
tasks.jsonl
```
generated with convergence criteria and source provenance per task
```
execution.md
```
contains plan overview, task table, pre-execution analysis, final summary
```
execution-events.md
```
contains chronological event stream with convergence verification
All tasks executed (or explicitly skipped) via direct inline execution
User informed of results and next steps

更新
```
execution.md
```
的最终摘要（统计数据、任务结果表）
为
```
execution-events.md
```
添加会话页脚
更新
```
tasks.jsonl
```
中每个任务的
```
_execution
```
状态

javascript

if (!autoYes) {
  AskUserQuestion({
    questions: [{
      question: `执行完成：${completedTasks.size}/${tasks.length}个任务成功。\n下一步：`,
      header: "执行后",
      multiSelect: false,
      options: [
        { label: "重试失败任务", description: `重新执行${failedTasks.size}个失败任务` },
        { label: "查看事件", description: "显示execution-events.md" },
        { label: "创建Issue", description: "从失败任务创建Issue" },
        { label: "完成", description: "结束工作流" }
      ]
    }]
  })
}

成功标准:

已生成tasks.jsonl，每个任务带收敛条件和来源溯源
```
execution.md
```
包含计划概述、任务表、执行前分析、最终摘要
```
execution-events.md
```
包含带收敛验证的 chronological事件流
所有任务已通过直接内联执行（或明确跳过）
已向用户告知结果和后续步骤

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
├── tasks.jsonl                # Phase 5: Unified JSONL with convergence + source (if quick execute)
├── execution.md               # Phase 5: Execution overview + task table + summary (if quick execute)
└── execution-events.md        # Phase 5: Chronological event log (if quick execute)

File	Phase	Description
`discussion.md`	1	Initialized with session metadata, finalized in Phase 4
`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
`tasks.jsonl`	5	Unified JSONL from recommendations, each line with convergence criteria and source provenance
`execution.md`	5	Execution overview: plan source, task table, pre-execution analysis, final summary
`execution-events.md`	5	Chronological event stream with task details and convergence verification

{projectRoot}/.workflow/.analysis/ANL-{slug}-{date}/
├── discussion.md              # 认知演进与讨论记录
├── exploration-codebase.json  # 阶段2：代码库上下文
├── explorations/              # 阶段2：多视角探索结果（如果已选择）
│   ├── technical.json
│   ├── architectural.json
│   └── ...
├── explorations.json          # 阶段2：单视角汇总发现结果
├── perspectives.json          # 阶段2：多视角发现结果及综合内容
├── conclusions.json           # 阶段4：带建议的最终综合内容
├── tasks.jsonl                # 阶段5：带收敛条件和来源的统一JSONL（如果使用快速执行）
├── execution.md               # 阶段5：执行概述 + 任务表 + 摘要（如果使用快速执行）
└── execution-events.md        # 阶段5： chronological事件日志（如果使用快速执行）

文件	阶段	描述
`discussion.md`	1	用会话元数据初始化，在阶段4定稿
`exploration-codebase.json`	2	代码库上下文：相关文件、模式、约束
`explorations/*.json`	2	各视角的探索结果（仅多视角）
`explorations.json`	2	单视角汇总发现结果
`perspectives.json`	2	多视角发现结果及跨视角综合内容
`conclusions.json`	4	最终综合内容：结论、建议、未解决问题
`tasks.jsonl`	5	从建议生成的统一JSONL，每行带收敛条件和来源溯源
`execution.md`	5	执行概述：计划来源、任务表、执行前分析、最终摘要
`execution-events.md`	5	带任务细节和收敛验证的 chronological事件流

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

维度用于指导分析的范围和重点：

维度	关键词	描述
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	权衡、影响分析、决策理由

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.

可选的多视角分析（默认单视角，最多4个）：

视角	重点	适用场景
Technical	实现模式、代码结构、技术可行性	理解实现方式和技术细节
Architectural	系统设计、可扩展性、组件交互	理解结构和组织方式
Security	安全模式、漏洞、访问控制	识别安全风险
Performance	瓶颈、优化、资源利用率	查找性能问题

选择：用户在阶段1中可多选最多4个视角，或默认使用单一综合视图。

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

深度	范围	描述
Quick	表层理解	快速概述，最小化探索
Standard	中等深度，覆盖全面	平衡的分析（默认）
Deep	全面详细的分析	深入的多轮调查

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.

当用户选择重点领域时，根据检测到的维度动态生成方向：

维度	可能的方向
architecture	系统设计、组件交互、技术选型、集成点、设计模式、可扩展性策略
implementation	代码结构、实现细节、代码模式、错误处理、测试方法、算法分析
performance	性能瓶颈、优化机会、资源利用率、缓存策略、并发问题
security	安全漏洞、认证/授权、访问控制、数据保护、输入验证
concept	概念基础、核心机制、基础模式、理论与原则、权衡与推理
comparison	方案比较、优缺点分析、技术评估、方法差异
decision	决策标准、权衡分析、风险评估、影响分析、实施影响

实现：展示2-3个与维度最相关的方向，允许用户多选并添加自定义方向。

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

markdown

undefined

在discussion.md中更新"当前认知"时遵循以下规则：

规则	描述
提升已确认的见解	将已验证的发现结果移至"已确认内容"
跟踪修正	记录重要的错误→正确的转变
聚焦当前状态	记录我们现在知道的内容，而非过程
避免时间线重复	不要将讨论细节复制到整合部分
保留关键认知	保留对未来有参考价值的见解

示例:

错误示例（杂乱）:

markdown

undefined

Current Understanding

当前认知

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


Good (consolidated):
```markdown

第一轮我们讨论了X，然后第二轮用户说Y...


正确示例（整合后）:
```markdown

Current Understanding

当前认知

What We Established

已确认内容

The authentication flow uses JWT with refresh tokens
Rate limiting is implemented at API gateway level

认证流程使用带刷新令牌的JWT
限流在API网关层面实现

What Was Clarified

已澄清内容

~~Assumed Redis for sessions~~ → Actually uses database-backed sessions

~~假设使用Redis存储会话~~ → 实际使用数据库存储会话
- 原因：假设错误的原因

Key Insights

关键见解

Current architecture supports horizontal scaling

undefined

当前架构支持水平扩展

undefined

Templates

模板

discussion.md Structure

discussion.md结构

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
Discussion Timeline: Round-by-round findings
- Round 1: Initial Understanding + Exploration Results
- Round 2-N: User feedback + direction adjustments + new insights
Synthesis & Conclusions: Summary, key conclusions, recommendations
Current Understanding (Final): Consolidated insights
Session Statistics: Rounds completed, findings count, artifacts generated

discussion.md文件随分析过程不断演进：

头部：会话ID、主题、开始时间、识别的维度
分析上下文：重点领域、视角、深度级别
初始问题：指导分析的关键问题
讨论时间线：逐轮发现结果
- 第一轮：初始理解 + 探索结果
- 第二轮至第N轮：用户反馈 + 方向调整 + 新见解
综合与结论：摘要、主要结论、建议
当前认知（最终）：整合后的见解
会话统计：完成的轮次、发现结果数量、生成的制品

Round Documentation Pattern

轮次记录模式

Each discussion round follows a consistent structure:

markdown

undefined

每轮讨论遵循一致的结构：

markdown

undefined

Round N - [Deepen|Adjust|Q&A] (timestamp)

第N轮 - [深化|调整|问答]（时间戳）

User Input

用户输入

What the user indicated they wanted to focus on

用户表示希望聚焦的内容

Analysis Results

分析结果

New findings from this round's analysis

Finding 1 (evidence: file:line)
Finding 2 (evidence: file:line)

本轮分析的新发现

发现1（证据：文件:行号）
发现2（证据：文件:行号）

Insights

见解

Key learnings and clarifications

关键认知和澄清内容

Corrected Assumptions

修正的假设

~~Previous assumption~~ → Corrected understanding
- Reason: Why the assumption was wrong

~~之前的假设~~ → 修正后的认知
- 原因：假设错误的原因

Open Items

未完成项

Remaining questions or areas for investigation

undefined

剩余的问题或需要调查的领域

undefined

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 in execution-events.md	User can retry, skip, or abort
Quick execute: verification fails	Mark criterion as unverified, continue	Note in events, manual check
Quick execute: no recommendations	Cannot generate tasks.jsonl	Suggest using lite-plan instead

情况	操作	恢复方式
未检测到代码库	正常流程，纯主题分析	不创建exploration-codebase.json继续执行
代码库搜索失败	基于现有上下文继续	在discussion.md中记录限制
无相关发现结果	扩大搜索关键词范围	询问用户以澄清
讨论中用户超时	保存状态，显示恢复命令	使用 `--continue` 恢复
达到最大轮次（5轮）	强制进入综合阶段	在结论中突出剩余问题
会话文件夹冲突	追加时间戳后缀	创建唯一文件夹并继续
快速执行：任务失败	在execution-events.md中记录失败	用户可重试、跳过或中止
快速执行：验证失败	将标准标记为未验证，继续执行	在事件中记录，需手动检查
快速执行：无建议	无法生成tasks.jsonl	建议使用lite-plan替代

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.

代码修改前需明确的用户确认：分析阶段严格为只读模式。任何代码变更（阶段5快速执行）都需要用户批准。

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

清晰的主题定义：详细的主题有助于更好地识别维度
用户上下文：理解用户的重点偏好有助于界定分析范围
视角选择：复杂主题选择2-4个视角，聚焦查询使用单视角
范围理解：明确深度期望可设置正确的分析强度

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

审查发现结果：进入讨论前检查探索结果
记录假设：跟踪你认为正确的内容以便后续修正
使用继续模式：恢复会话以基于之前的发现结果继续，而非重新开始
接受修正：将错误→正确的转变视为有价值的认知
有意义地迭代：每轮讨论应切实优化认知

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

基于证据：每个结论都应引用特定代码或模式
置信度级别：为结论标注置信度（高/中/低）
时间线清晰：使用清晰的时间戳以确保可追溯
跟踪演进：记录认知在各轮次之间的变化
可操作项：生成具体、可执行的建议
多视角综合：使用多视角时，记录共识/分歧主题

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
Context is already sufficient — no additional exploration needed
Want a streamlined analyze → JSONL plan → direct execute pipeline
Tasks are relatively independent and can be executed serially

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

当以下情况时使用analyze-with-file:

需协作探索复杂主题并保留文档记录轨迹
需要多轮迭代优化认知
决策需要探索多个视角
实施前需要建立共同认知
希望记录认知的演进过程

当以下情况时使用快速执行（阶段5）:

分析结论包含清晰、可执行的建议
上下文已足够充分 — 无需额外探索
想要简化的分析→JSONL计划→直接执行流程
任务相对独立且可串行执行

当以下情况时考虑替代方案:

需要特定bug诊断 → 使用
```
debug-with-file
```
需要生成新想法/解决方案 → 使用
```
brainstorm-with-file
```
需要带并行视角的复杂规划 → 使用
```
collaborative-plan-with-file
```
准备实施 → 使用
```
lite-plan
```
需要需求分解 → 使用
```
req-plan-with-file
```

现在针对主题执行analyze-with-file工作流: $TOPIC