investigate

用途

investigate 是一个系统化根因调试技能（Skill），用于在修复缺陷前先完成根因调查。其“铁律”是：没有先做根因调查，就不允许进行修复（no fixes without root cause investigation first）。

主要能力

该技能将调试过程划分为四个阶段：

1. 根因调查（Root Cause Investigation）
2. 模式分析（Pattern Analysis），涉及 6 种已知模式
3. 假设检验（Hypothesis Testing），采用“三振出局规则”（3-strike rule）
4. 实现（Implementation）

最终输出结构化的调试报告（Structured debug report）。

使用方式

技能通过一段预置脚本运行（preamble）。脚本会执行以下操作：检查是否有可用更新；在用户配置目录下创建并维护会话文件；清理超过 120 分钟的旧会话文件；读取 gstack 配置（如 gstack_contributor、proactive、telemetry）；输出当前 Git 分支、REPO_MODE、LAKE_INTRO 等状态；并向 ~/.gstack/analytics/skill-usage.jsonl 追加本次技能使用记录。

脚本运行后，会根据配置值决定后续行为，例如当 PROACTIVE 为 "false" 时不主动建议 gstack 技能；当出现 UPGRADE_AVAILABLE 时读取升级文档并执行内联升级流程；当 LAKE_INTRO 为 "no" 时介绍 Completeness Principle（完整性原则）并询问是否打开相关文章。

相关机制

• AskUserQuestion 格式：要求每次提问都重新说明项目、当前分支与任务，用通俗语言解释问题，给出推荐项并标注完整性评分（Completeness 1–10）。
• Completeness Principle（“Boil the Lake”）：在 AI 辅助下优先选择完整实现而非走捷径，并给出人工团队与 CC+gstack 的耗时压缩比参考表。
• Repo Ownership Mode：区分 solo、collaborative、unknown 三种模式，在单人模式下主动修复分支外问题，在协作模式下通过 AskUserQuestion 上报。
• See Something, Say Something：任何流程步骤中发现异常都应简短上报，不得静默放过。
• Search Before Building：强调先搜索再构建，区分三层知识（成熟方案、新热门方案、第一性原理），并记录 EUREKA 时刻。
• Contributor Mode：贡献者模式下可提交 gstack 工具的相关体验报告（field report）。
• Completion Status Protocol：完成后以 DONE、DONE_WITH_CONCERNS、BLOCKED、NEEDS_CONTEXT 之一报告状态，并提供升级（Escalation）机制；同一任务尝试 3 次未成功应停止并升级。
• Telemetry：技能流程结束后记录遥测事件（含技能名、时长、结果等）。
• Plan Status Footer：处于计划模式且即将调用 ExitPlanMode 时，检查并写入 GSTACK REVIEW REPORT 部分。

适用场景

适用于需要严格定位缺陷根因、避免未查明原因就盲目修改的调试工作流。

限制

资料中未提供该技能的收费、价格、支持平台、具体安装命令、效果数据等信息，以上内容暂未提供。

引用文档

以下为作者声明的引用来源，保留指定版本、署名和许可。

作者的来源声明

• garrytan/gstack/investigate/SKILL.md — 署名：Garry Tan；许可：MIT；版本：f4bbfaa5bdfd2d6ce59541c2145432febde57fed。