Analyze Project

/analyze-project — 根因分析师工作流

分析 ~/.gemini/antigravity/brain/ 中的 AI 辅助编码会话，生成报告，不仅解释发生了什么，还要解释为什么发生、谁/什么导致的，以及下次应该改变什么。

目标

对于每个会话，确定：

1. 从初始请求到最终执行的工作发生了什么变化
2. 主要原因是：
   • 用户/规格
   • 智能体
   • 仓库/代码库
   • 验证/测试
   • 合理的任务复杂度
3. 开场提示词是否充分
4. 哪些文件/子系统反复与困难相关
5. 哪些改变最能改善未来的会话

何时使用

• 你需要对 AI 辅助编码会话进行事后分析，特别是出现范围漂移或重复返工时。
• 你需要根因分析，区分用户/规格问题与智能体错误、仓库摩擦或验证缺口。
• 你需要基于证据的改进建议，用于优化未来的提示词、仓库健康度或交付工作流。

全局规则

• 将 .resolved.N 计数视为迭代信号，而非失败证明
• 区分人类添加的范围、必要的发现范围和智能体引入的范围
• 区分智能体错误与仓库摩擦
• 每个诊断必须包含证据和置信度
• 置信度级别：
  • 高 = 直接的工件/时间戳证据
  • 中 = 多个支持信号
  • 低 = 合理推断，未直接证明
• 证据优先级：
  • 工件内容 > 时间戳 > 元数据摘要 > 推断
• 如果证据薄弱，明确说明

步骤 0.5：会话意图分类

从目标 + 工件分类主要会话意图：

• DELIVERY
• DEBUGGING
• REFACTOR
• RESEARCH
• EXPLORATION
• AUDIT_ANALYSIS

记录：

• session_intent
• session_intent_confidence

使用意图来上下文化严重性和返工形态。 不要用与狭窄交付会话相同的标准评判探索性或研究会话。

步骤 1：发现对话

1. 从系统上下文读取可用的对话摘要
2. 列出用户 Antigravity brain/ 目录中的对话文件夹
3. 构建对话索引，包含：
   • conversation_id
   • title
   • objective
   • created
   • last_modified
4. 如果用户提供了关键词/路径，筛选匹配的对话；否则分析全部

输出：待分析的对话索引列表。

步骤 2：提取会话证据

对于每个对话，读取以下内容（如果存在）：

核心工件

• task.md
• implementation_plan.md
• walkthrough.md

元数据

• *.metadata.json

版本快照

• task.md.resolved.0 ... N
• implementation_plan.md.resolved.0 ... N
• walkthrough.md.resolved.0 ... N

额外信号

• 其他 .md 工件
• 工件更新的时间戳
• 计划/演练中提到的文件/文件夹/子系统名称
• 验证/测试语言
• 明确的验收标准、约束、非目标和文件目标

每个对话记录：

生命周期

• has_task
• has_plan
• has_walkthrough
• is_completed
• is_abandoned_candidate = 存在任务但无演练

修订 / 变更量

• task_versions
• plan_versions
• walkthrough_versions
• extra_artifacts

范围

• task_items_initial
• task_items_final
• task_completed_pct
• scope_delta_raw
• scope_creep_pct_raw

时间

• created_at
• completed_at
• duration_minutes

内容 / 质量

• objective_text
• initial_plan_summary
• final_plan_summary
• initial_task_excerpt
• final_task_excerpt
• walkthrough_summary
• mentioned_files_or_subsystems
• validation_requirements_present
• acceptance_criteria_present
• non_goals_present
• scope_boundaries_present
• file_targets_present
• constraints_present

步骤 3：提示词充分性

对开场请求按 0–2 分制评分：

• 清晰度
• 边界性
• 可测试性
• 架构特异性
• 约束意识
• 依赖意识

创建：

• prompt_sufficiency_score
• prompt_sufficiency_band = 高 / 中 / 低

然后记录哪些缺失的提示词要素可能导致了后续摩擦。

不要默认惩罚简短的提示词；狭窄、明显的任务仍然可以有高充分性。

步骤 4：范围变更分类

将范围变更分类为：

• 人类添加的范围 — 超出原始任务的新请求
• 必要的发现范围 — 正确完成原始任务所需的工作
• 智能体引入的范围 — 智能体可能引入的不必要工作

记录：

• scope_change_type_primary
• scope_change_type_secondary（可选）
• scope_change_confidence
• 证据

记住一个简短示例作为校准：

• 人类添加："顺便重构附近的代码"
• 必要发现：隐藏依赖必须修复才能使原始任务工作
• 智能体引入：未请求且不需要的额外清理或重新设计

步骤 5：返工形态

将每个会话分类为一个主要模式：

• 干净执行
• 早期重规划后稳定完成
• 渐进式范围扩展
• 重开/关闭循环
• 后期验证循环
• 中途放弃
• 探索性 / 研究会话

记录：

• rework_shape
• rework_shape_confidence
• 证据

步骤 6：根因分析

对于每个非干净会话，分配：

主要根因

以下之一：

• SPEC_AMBIGUITY
• HUMAN_SCOPE_CHANGE
• REPO_FRAGILITY
• AGENT_ARCHITECTURAL_ERROR
• VERIFICATION_CHURN
• LEGITIMATE_TASK_COMPLEXITY

次要根因

如果实质相关则可选

根因指导

• SPEC_AMBIGUITY：开场请求缺乏边界、目标、标准或约束
• HUMAN_SCOPE_CHANGE：范围扩展是因为用户扩大了任务
• REPO_FRAGILITY：隐藏耦合、脆弱文件、不清晰的架构或环境问题迫使额外工作
• AGENT_ARCHITECTURAL_ERROR：错误的文件、错误的假设、错误的方法、幻觉结构
• VERIFICATION_CHURN：实现基本可行，但测试/验证导致循环
• LEGITIMATE_TASK_COMPLEXITY：修订对于难度是预期的，且明显无法避免

每个根因分配必须包含：

• 证据
• 为什么拒绝更强的替代原因
• 置信度

步骤 6.5：会话严重性评分（0–100）

为每个会话分配严重性分数以优先关注。

组成部分（求和，限制 0–100）：

• 完成失败：0–25（abandoned = 25）
• 重规划强度：0–15
• 范围不稳定性：0–15
• 返工形态严重性：0–15
• 提示词充分性缺陷：0–10（low = 10）
• 根因影响：0–10（REPO_FRAGILITY / AGENT_ARCHITECTURAL_ERROR 最高）
• 热点复发：0–10

分级：

• 0–19 低
• 20–39 中等
• 40–59 显著
• 60–79 高
• 80–100 严重

记录：

• session_severity_score
• severity_band
• severity_drivers = 前 2–4 个贡献者
• severity_confidence

将严重性用作优先级信号，而非判决。始终解释驱动因素。 使用会话意图上下文化严重性，以免研究/探索会话被过度惩罚。

步骤 7：子系统 / 文件聚类

跨所有对话，按文件、文件夹或子系统聚类重复困难。

对于每个聚类，计算：

• 涉及的对话数量
• 平均修订次数
• 完成率
• 放弃率
• 常见根因
• 平均严重性

目标：识别摩擦主要是提示词驱动、智能体驱动，还是集中在特定仓库区域。

步骤 8：比较队列

比较：

• 首次成功 vs 重规划会话
• 完成 vs 放弃
• 高提示词充分性 vs 低提示词充分性
• 窄范围 vs 高范围增长
• 短会话 vs 长会话
• 低摩擦子系统 vs 高摩擦子系统

对于每个比较，识别：

• 实质差异是什么
• 哪些提示词特征与更顺畅的执行相关
• 哪些仓库特征与重复困难相关

不要只是重述平均值；提取谨慎的、基于证据的模式。

步骤 9：非显而易见发现

生成 3–7 个不是简单指标重述的发现。

每个发现必须包含：

• 观察
• 为什么重要
• 证据
• 置信度

强发现示例：

• 重规划聚集在弱文件定位而非弱验收标准
• 范围增长通常在初始成功后开始，表明成功后人类扩展
• 认证相关困难更多由仓库脆弱性驱动而非智能体幻觉

步骤 10：报告生成

创建具有以下结构的 session_analysis_report.md：

📊 会话分析报告 — [项目名称]

生成时间：[时间戳]
分析对话数：[N]
日期范围：[最早] → [最晚]

执行摘要

阈值：

• 首次成功：🟢 >70 / 🟡 40–70 / 🔴 <40
• 范围增长：🟢 <15 / 🟡 15–40 / 🔴 >40
• 重规划率：🟢 <20 / 🟡 20–50 / 🔴 >50

平均严重性指导：

• 🟢 <25
• 🟡 25–50
• 🔴 >50

注意：平均严重性是聚合健康信号，与会话严重性分级不同。

然后添加简短的叙述性摘要，说明哪些进展顺利、哪些出现问题，以及主要问题是提示词质量、仓库脆弱性、工作流纪律还是验证循环。

根因分布

提示词充分性分析

• 高充分性提示词的共同特征
• 低充分性提示词中常见的缺失输入
• 哪些缺失的提示词要素与重规划或放弃最相关

范围变更分析

区分：

• 人类添加的范围
• 必要的发现范围
• 智能体引入的范围

返工形态分析

总结会话中的主要失败模式。

摩擦热点

展示与重规划、放弃、验证循环和高严重性最相关的文件/文件夹/子系统。

首次成功

列出最干净的会话并提取成功因素。

非显而易见发现

列出 3–7 个基于证据的发现及置信度。

严重性分诊

列出最高严重性的会话，说明最佳干预是：

• 提示词改进
• 范围纪律
• 针对性技能/工作流
• 仓库重构 / 架构清理
• 验证/测试工具改进

建议

对于每个建议，使用：

• 观察到的模式
• 可能原因
• 证据
• 要做的改变
• 预期收益
• 置信度

每个对话的详细分解

步骤 11：可选分析后改进

如果合适，还可以：

• 用重复失败模式和脆弱子系统更新任何本地项目健康或记忆工件（如果存在）
• 从高充分性 / 首次成功会话生成 prompt_improvement_tips.md
• 当相同子系统或任务序列反复导致困难时，建议缺失的技能或工作流

仅在模式重复出现时推荐工作流/技能。

最终输出标准

工作流必须产出：

1. 指标摘要
2. 根因诊断
3. 提示词充分性评估
4. 子系统/摩擦图
5. 严重性分诊和优先级
6. 基于证据的建议
7. 非显而易见发现

优先选择明确的不确定性而非虚假的精确性。

局限性

• 仅当任务明确匹配上述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，停止并请求澄清。