常见踩坑
来自真实交付复盘。每条先写会出什么事，再写怎么做才对，并标出通常发生在哪一步。派发前可用文末清单快速自检。
1. 迁到错误分支
发生在： same 的目标确认阶段。
出什么事： 说「开始迁移 / 交接到项目C…」后，Agent 在当前所在分支直接改，结果改到了发布分支。
怎么做：
- 先看每个目标仓：现在在哪条分支、是否干净、是不是这个任务的分支
- 不对就先切到正确功能分支，再改
- 禁止「人在哪就改哪」
→ same
2. 源仓库没提交就多项目派发
发生在： dispatch 从预览进入正式派发时。
出什么事： 预览过了，一点真正派发就被拦住。
怎么做：
- 源仓库先 commit
- 再预览 → 你批准 → 再派发
- 被拦住时先补提交，不要强行派发
→ dispatch
3. 把「调度通过」当成「已经上线」
发生在： dispatch 报告项目验收通过之后。
出什么事： 调度显示验收通过，但代码还没 push，也没合进 dev。
怎么做：
| 阶段 | 意思 |
|---|---|
| 调度验收通过 | 记录和证据齐了 |
| 远端落地 | 还要 push，需要时用 end 合分支 |
4. 把 Grok 和 Codex 的用法抄反
发生在： dispatch 选择宿主和工作方式时。
出什么事： 以为一定要开很多会话，或把两种工具的做法弄反。
怎么做：
| 工具 | 日常习惯 |
|---|---|
| Grok / Claude | 默认绑 一个会话；不同项目可同时改，同一项目仍串行 |
| Codex | 可以按能力开多个会话 / 线程 |
细节见宿主说明。
5. 升级后对话里没有新命令（如 /jj-init）
发生在： 以前装过 jj-flow，后来包里多了新 skill。
出什么事： ~/.grok/skills 里有 jj-ralph / jj-same 等，但没有 jj-init。斜杠菜单也没有 /jj-init。旧版安装在已有文件时会整组拒绝写入。
怎么做：
npx @brewer/jj-flow@latest install-skill --platform all再次安装会补上缺失项，默认不覆盖已有文件；覆盖安装请加 --force。然后新开一轮对话，输入 /jj。
6. 回退时自动擅自改动 Git
发生在： dispatch 处理回退或重新打开交付时。
出什么事： 你说「回退某次交付」，Agent 直接 revert/reset，与你预期的干净历史不一致。
怎么做：
- 先处理调度记录（能否重开、能否再做）
- Git 先探测「推没推、合没合」→ 列选项给你 → 你点了再执行
- 本地干净未推常适合 reset；已推或已合常适合 revert；不会随意 force
→ dispatch
7. 只靠聊天就当「做完了」
发生在： ralph 验收 / 归档或 dispatch 验收之后。
出什么事： 任务显示归档通过，但审查还开着问题；或任务说明还是旧状态。
怎么做：
- 只看：任务记录、Git 提交、审查文件、调度记录
- 还有未解决的中等问题，不要当作验收通过
- 调度通过后，任务说明要和最新状态一致
→ 证据怎么算数
8. team 完成就当成验收通过
发生在： team-coordinate / lifecycle / swarm 报告完成之后。
出什么事： team 提示 complete，就以为 ralph ACCEPT 或 dispatch VERIFIED 已经通过。
怎么做：
| 引擎 | 产物 | 算不算验收 |
|---|---|---|
| team-coordinate | 动态角色协作产物 | 不算 |
| team-lifecycle | 规格 / 计划 / 实现产物 | 不算 |
| team-swarm | 候选方案 / 推荐 | 不算 |
验收仍只认 ralph 的记录和证据，或 dispatch 的验收记录。team 产物可以写进证据里引用，但不会自动打开验收门。
9. 以为每次都必须独占目录
发生在： ralph / dispatch 开始选择工作区时。
出什么事： 每次都开单独 worktree，或反过来在脏的主分支上直接写。
怎么做： 默认在功能分支上改；只有要隔离时才单独目录。分支或工作区不确定就先问。
10. 把项目族角色名擅自改成 source / target
发生在： same / dispatch 解析目标项目时。
出什么事： 叫成 source / target 后指向错误仓库。
怎么做： 会话和调度里用稳定的项目族称呼（文档示例为项目A / 项目B / 项目C）；用项目地图里的 path 对照，别靠别名猜。
11. 收工时把 staging 当成 dev
发生在： end 选择合入分支、打印收工计划时。
出什么事： 仓库里既有 dev 又有 staging，Agent 只因为历史提交或构建脚本里出现 staging，就把功能合进预发分支。
怎么做：
- 没写
integration=、文档 /naming.json也没点名合入分支时：有dev就只合dev - git log、MR 标题、默认远端指向、功能分支来源、仓库里有
staging分支、构建脚本名里带 staging，都不算约定 - 要合入预发必须写
integration=staging，或文档明确点名合入分支 - 执行前那一行
work → integration要看得出依据，方便当场拦住
→ end
复盘（仓库内，站点不收录）：docs/evaluations/EP-20260828-jj-end-staging-not-dev.md
12. 收工遇到冲突就整段放弃，或只解一半
发生在： end 合并工作分支时。
出什么事： $jj-end 把「两边都在演进」的 Vue/文档冲突标成 complex，整段 merge --abort（feat/dynamic-form：AGENTS.md 策略段、readonly vs uploadDisabled、草稿恢复 helper、LOGO 条件）。或者只解了 import、业务函数还留着，半成品 merge。一有冲突就停也是同一类问题。
怎么做：
- 先打分类表：每个冲突文件
self-merge或unhandleable；拿不准的交给你判断 - 默认自行合并：能一句话说清如何合并、不发明产品决策 → 解完继续 push 合入（Vue/文档/条件守卫不同也算）
- 只有真正无法合并（同一产品开关两边相反且无法判断、二进制/密钥、读完仍无法陈述解法）→
merge --abort，回到工作分支，把表给你 - 不要只解子集再 abort；解完不能留下
<<<<<<< - 第一眼「看起来复杂」不是停手理由，要读 hunk 和上下文再判
→ end
派发前 10 秒自检
- [ ] 源仓库已经 commit
- [ ] 每个目标仓的分支对得上这次任务
- [ ] 分支或目录拿不准时，已经问过
- [ ] 说清楚要不要 push、要不要合进 dev
更细的复盘在仓库 docs/evaluations/（偏内部，日常上手不用读）。