torch_bisect 是一个面向 PyTorch 与 TorchTitan 开发的 git bisect 排查技能，目标是在 PyTorch 仓库中找到导致 TorchTitan 出现回归问题的第一个坏提交。
用途
当需要排查 TorchTitan 在某个 PyTorch 版本或提交上出现异常，并希望定位具体是哪一个 PyTorch 提交引入该问题时，可使用此技能。它按 git bisect 流程在 PyTorch 仓库中逐步缩小提交范围，最终给出首个坏提交。
主要能力与工作流程
技能分为四个阶段。
阶段一：收集信息。 记录 TorchTitan 目录，并检查缓存文件 ~/.claude/torchtitan_torch_bisect_cache.json 是否存在；若存在则展示缓存值，允许用户复用或覆盖。收集内容包括：PyTorch 仓库绝对路径、每次切换提交后重新编译 PyTorch 的构建命令、在 TorchTitan 目录下运行的测试命令（好提交退出码为 0，坏提交非 0，仅依据退出码判断）、已知正常提交（哈希或日期）、以及测试超时策略（超过 10 分钟时自动标记为坏还是每次询问）。收集完成后可保存到缓存。
阶段二：准备。 先检查 GitHub 连通性，若无法访问则提示检查网络或代理设置，在 Meta 内部服务器上建议设置 https_proxy=http://fwdproxy:8080，连通性确认前不继续。随后执行 git fetch origin，检查是否已有进行中的 bisect（若有则请用户重置或中止），解析已知正常提交（哈希需验证，日期则从 origin/main 中查找指定日期前的最近提交并请用户确认），坏提交固定为 origin/main，并展示提交数量和预计步骤数。之后依次执行 git bisect start、git bisect bad origin/main、git bisect good <good>，任一步失败则展示错误并执行 git bisect reset 后再询问用户。
阶段三：二分循环。 重复执行：在 PyTorch 目录运行构建命令（超时 600000ms），失败时展示最后 50 行并让用户选择跳过、重试或中止；在 TorchTitan 目录运行测试命令（超时 600000ms），以退出码判断好坏，超时按阶段一设定的策略处理，不分析日志内容；在 PyTorch 目录执行 git bisect good 或 git bisect bad 记录结果。输出含“is the first bad commit”时进入报告阶段，含“Bisecting:”时继续循环，无法继续缩小（跳过过多）时提示用户并建议中止。每步后打印步骤编号、提交哈希、好坏判定和剩余数量。
阶段四：报告与清理。 捕获 git bisect log 与 git show --stat <bad_commit>，从提交标题中按 (#NNNNN) 模式提取 PR 编号，若找到则用 gh pr view <N> --repo pytorch/pytorch --json title,body,url 获取 PR 详情，回退链接为 https://github.com/pytorch/pytorch/pull/<N>。随后执行 git bisect reset，输出包括首个坏提交、提交信息、作者、日期、关联 PR（标题、链接、正文前约 20 行）、改动文件和完整 bisect 日志。若未找到 PR 编号则省略该部分，且不诊断根本原因。
使用方式
该技能通过调用 /torch_bisect 或在用户希望二分排查 PyTorch 时触发。使用时需提供 PyTorch 本地仓库绝对路径、构建命令和测试命令；技能强调始终使用绝对路径，因为 shell 状态不会在 Bash 调用之间保留。
适用场景
适用于 TorchTitan 在 PyTorch 更新后出现构建或测试失败、需要定位引入问题的提交，并且用户已具备可重复的构建与测试命令的环境。
限制
测试结果仅以退出码判定，不分析日志内容；技能不诊断根本原因；需要 GitHub 连通性才能拉取代码和查询 PR；若二分过程中跳过提交过多导致无法继续，需用户决定是否中止。