当用户想知道某段代码为何变成现在这样时，用 git…

针对指定文件行范围或粘贴的代码片段，追溯最近一次改动并解释其历史原因。

适用场景

解决思路

1. 先解析目标代码块：若用户未提供文件路径加精确行号/范围或粘贴片段，则要求其补充目标代码并停止，不运行任何命令。
2. 若用户给出 `path:line` 或 `path:start-end`，直接使用该行或范围，只读取该目标后再解释；若路径不存在、文件无法读取或行号超出文件范围，直接说明并停止。
3. 若用户给出路径加片段：用 `grep -n -F -- "<distinctive snippet line>" "<path>"` 做固定字符串匹配定位候选位置，只读取命中点附近的小窗口，在候选窗口中确认精确片段，转换为 `start-end` 行号。
4. 匹配前先归一化前导缩进和行尾空白；若片段出现多次，报告歧义并列出候选范围，不要静默选择其一；若无法精确找到片段，直接说明并停止，不要推断邻近匹配。
5. 仅在目标已解析为当前文件中的实际行号后，运行 `git blame --porcelain -L <start>,<end> -- "<path>"`。
6. 若因文件未跟踪导致 blame 失败，将整个目标范围标记为未跟踪文件、无提交历史，保留精确片段并继续做回退代码行为分析。
7. 若 blame 报告全零或 `Not Committed Yet` 之类的未提交伪提交，将这些范围标记为本地未提交改动，不对其运行 `entire checkpoint explain`；其他范围若解析出真实提交则继续处理。
8. 从 blame 输出中识别目标范围内的每个 blame 块，将解析到同一提交的相邻目标行合并为一个连续匹配块；对每个匹配块收集：行范围、当前文件中该精确范围的代码片段、提交哈希、以及有助于溯源或回退上下文的作者/摘要。
9. 收集所有匹配块中唯一的真实提交 SHA，同时保留每个不同范围；排除未跟踪和本地未提交伪提交；建立提交 SHA 到所有归属该提交的目标范围的映射，不要对共享同一提交的多个范围分别运行 `entire checkpoint explain`。
10. 若解析出的目标跨越超过 5 个唯一真实提交，在运行 `entire explain` 前停止，报告匹配范围并请用户缩小范围或确认是否深入查找。
11. 保留目标解析时读取的精确片段，以便最终答案展示每条溯源对应哪段代码；仅当某范围的片段尚未捕获时才重新读取该匹配块。
12. 对映射中每个唯一提交 SHA 恰好运行一次 `entire checkpoint explain --commit <commit-sha> --no-pager`；若有多个唯一提交且环境支持并行工具调用，则并行执行这些独立查询。
13. 不要使用 `--search-all`，除非用户明确要求扩大失败查询的范围。
14. 若该命令失败，不要额外查询提交元数据，也不要扫描原始会话文件；将该范围标记为回退代码行为分析，并报告 Entire transcript 查询失败；仅当错误有助于用户修复问题（如认证或缺失远程配置）时才附上命令错误。
15. 若提交视图揭示了 checkpoint ID 但仍不足以回答用户问题，收集该 checkpoint ID 用于展开；在运行 checkpoint 查询前对所有提交视图中的 checkpoint ID 去重；若多个提交引用同一 checkpoint，只展开一次并将结果映射回所有相关范围。
16. 对每个需要更多细节的唯一 checkpoint ID 运行 `entire checkpoint explain --checkpoint <checkpoint-id> --full --no-pager`。
17. 不要自动运行原始 transcript 展开；若 `--full` 失败或不足，将受影响范围标记为当前代码回退分析，除非用户明确要求原始 transcript 细节；仅在明确要求时才运行 `entire checkpoint explain --checkpoint <checkpoint-id> --raw-transcript --no-pager`。
18. 用收集到的输出回答：agent 当时想做什么、该块为何改变、导致最终代码的任何约束、bug、边界情况或重构压力。
19. 默认不要展示原始 `entire checkpoint explain` 输出，只总结与目标范围相关的部分。
20. 若提交没有 checkpoint ID，仅使用 `entire checkpoint explain --commit` 返回的提交级上下文做溯源，并将该范围标记为回退代码行为分析，明确说明“无 checkpoint 支持的摘要；未引用任何 Entire checkpoint”。
21. 若存在 checkpoint ID 但 `entire checkpoint explain --checkpoint` 无法加载，在答案中保留该 checkpoint ID 并说明“引用了 checkpoint <id>，但该 checkpoint 在本地或远程不可用”；仅当错误有助于用户修复问题（如认证或缺失远程配置）时才附上命令错误。
22. 若 checkpoint 能加载但 `--full` 失败，说明 checkpoint 元数据可用但完整 transcript 展开失败；若未明确要求原始 transcript 细节，说明未自动展开；用 `entire explain --commit` 输出回答 checkpoint 支持的事实，其余用当前代码回退分析。
23. 将每个唯一提交的解释映射回归属该提交的每个目标范围。
24. 对任何处于 checkpoint 支持上下文不可用状态的范围，仍要回答当前代码做什么：只读取目标块及最小必要外围作用域（如所在函数、类型、导入、常量）；仅当无法从局部上下文理解时才用 `grep -n -F` 检查直接调用点或定义；解释可观察行为、输入、输出、副作用和重要分支；不要将其表述为历史意图、checkpoint 理由或 agent transcript 摘要；说明仅凭当前代码无法得知的内容。
25. 响应格式：在本次技能调用第一个成功解析代码的响应开头输出 `Entire What Happened:`，后跟空行；仅对本次调用的第一个成功解析代码响应使用该头部，未解析输入的响应（片段未找到、片段歧义、路径或范围无效）不要使用该头部；若目标已解析但无 checkpoint 支持上下文，仍使用该头部并明确标注为当前代码回退分析而非 checkpoint 摘要。
26. 头部之后，从允许示例中随机选一行简短、原创、非歌词的 “Tell me why” 行，例如 `Tell me why: the blame points here.`、`Tell me why: the diff left a trail.`、`Tell me why: the context starts here.`；不要引用、改写或模仿 Backstreet Boys 歌词或任何其他歌曲歌词。
27. 随后以简短溯源摘要开头，每个范围使用 Rule 7 状态之一，格式为 `Matches` 列表，每项形如 `- <path>:<start>-<end> -> commit <sha> | checkpoint <id>` 并附匹配代码片段；状态包括：有 checkpoint、无 Entire checkpoint、Entire transcript 查询失败、checkpoint 不可用、checkpoint 仅元数据且 transcript 展开失败、本地未提交改动无提交历史、未跟踪文件无提交历史。
28. 对有 checkpoint 支持的范围，按每个不同匹配块给出一个简短 `Why` 小节：`- <path>:<start>-<end>: <2-4 句解释该块上次为何改变>`。
29. 对无 checkpoint 支持上下文的范围，改用单独小节 `Current-code fallback (not checkpoint-backed)`：`- <path>:<start>-<end>: <2-4 句解释当前代码做什么，以及无 checkpoint 历史时无法推断的局限>`。
30. 片段指引：优先使用文件中精确匹配的行；片段紧贴匹配块，避免无关外围代码；若块很长，包含仍能让用户识别的最小连续摘录并说明已截断；当输入是粘贴片段时，在答案中包含解析出的行范围。

适用边界 · 注意事项

• 用户询问某个符号、文件或功能的宽泛原始意图时，应改用 `explain` 技能，而不是本技能。
• 用户未提供文件路径、行范围或粘贴片段时，不要运行命令或使用 `Entire What Happened:` 头部，应先要求补充目标代码。
• 不要手动翻查 `.git/entire-sessions/` 或原始 transcript 文件来获取提交溯源；也不要使用实验性的 `entire why`。