bugfix-worktree

Bugfix Worktree

目的

建立一个半自动 bug 修复流程：一个 bug 对应一个分支、一个 worktree、一个独立修复窗口。

issues/<版本>/*.csv 是任务控制表，放在要修复的业务项目根目录里，例如 /path/to/business-project/issues/2026-06-25-test/bug_batch.csv。它不要放进任何单个 bug 的 worktree，也不要放到全局 skill 项目里。

单个 bug 的详细过程记录放在外部版本目录，例如 issues/<版本>/tasks/BUG-013-TASK.md。不要只放在 worktree 里，因为 worktree 是临时代码现场，合并后还可能需要回看任务记录。

这个 skill 不负责把模糊 bug 猜成真相。优先使用用户已经人工确认过的描述和明确的验证方法。

职责边界：本 skill 主要负责领取 bug、创建 worktree、修复、AI 自证验证、构建待验证 APK、按需安装。用户验证通过后的合并和 worktree 清理，优先交给 $bugfix-done。

Issues 表

推荐文件位置：

issues/<版本>/bug_batch.csv

例如：

issues/2026-06-24/bug_batch.csv

推荐列：

• bug_id
• 标题 或 title
• 问题描述
• 人工确认描述
• 状态
• branch
• worktree_path
• base_repo
• target_branch
• 复现场景
• 验收标准
• ai_verify_plan
• ai_verify_cmd
• ai_verify_result
• ai_verify_evidence
• apk_path
• install_device
• human_verify_result
• human_verify_note
• commit
• task_file
• 备注

推荐状态：

draft, ready, needs_info, in_progress, fixed, ai_verified, apk_built, installed, human_verified, merged, integration_verified, worktree_removed, blocked

如果 CSV 缺少流程列，先备份，再补列。保留原始 bug 字段，不要破坏用户从腾讯文档导出的内容。

写入 CSV 前，在同目录创建简单锁文件，例如 <csv>.lock。如果锁文件很新，停止并提示可能有另一个窗口正在更新。只有确认锁已陈旧时，才说明原因后移除。

准备阶段

$bugfix-worktree 不应该在真正开始修 bug 时才频繁追问用户。应在从 $bug2csv 导出文件生成 issues/<版本>/bug_batch.csv 时，先把每条 bug 整理到可执行状态。

准备阶段推荐做法：

1. 保留原始 问题描述。
2. 用户或 AI 补充 人工确认描述，尽量写清楚真实复现过程。
3. AI 根据人工确认描述生成 复现场景 和 验收标准 草案。
4. 用户只需要确认明显不对或缺关键条件的行。
5. 信息足够开始修的行标记为 ready。
6. 信息明显不足、会导致 AI 猜测的行标记为 needs_info，先不要领取修复。

字段含义：

• 复现场景：这个 bug 在什么条件下发生。写设备、系统、账号状态、连接方式、前置操作等。它回答“在哪里、怎么触发”。
• 验收标准：修好后怎样算通过。写可观察结果，例如“只出现一个弹窗”“点击后跳到系统权限页”“PC 端持续有声音”。它回答“怎么判断修好了”。

示例：

bug_id,人工确认描述,复现场景,验收标准,状态
BUG-013,等待接收设备同意超时会出现两个弹窗,安卓发起端向 PC 接收端发起投屏，PC 不点击同意，等待请求超时,超时后安卓端只出现一个超时提示，不同时出现普通超时弹窗和连接失败超时弹窗,ready

单 bug TASK 文件

每个 bug 必须维护一个单 bug 过程记录文件，放在当前版本目录：

issues/<版本>/tasks/<bug_id>-TASK.md

例如：

issues/2026-06-24/tasks/BUG-013-TASK.md