fix

用途

fix 是一个执行者（executor）技能，面向 motiondivision/motion 仓库。它的目标是把一个 GitHub issue、一个已开启的 PR，或 plans/ 目录下的计划文件，推进为一个可合并（merge-ready）的 PR。技能假设更昂贵的规划模型已经完成了思考，执行者只需严格按规范实现、证明其有效并交付 PR。执行者没有规划会话的上下文，所需信息全部来自计划文件、GitHub issue/PR 以及仓库的 CLAUDE.md，写代码前必须阅读这三者。

输入解析

参数可以是：

计划文件路径（如 plans/issues/pr-3724.md 或 plans/001-animate-layout-public-api.md），需完整阅读；计划是该技能的主要输入。
计划编号（如 008），在 plans/ 或 plans/issues/ 中查找匹配文件。
GitHub issue 编号（如 #3741），先运行 gh issue view <number>，并检查 plans/issues/ 中是否已有对应计划（grep 该编号）；若有，以计划为准。
PR 编号，运行 gh pr view <number> 和 gh pr checks <number>，并检查 plans/issues/ 中是否有覆盖该 PR 的计划；若有，以计划为准。

如果参数有歧义或匹配不到任何内容，列出找到的结果并停止，不得猜测意图。

硬性规则

计划即规范。不得重新设计、扩大范围或“顺手改进”。若计划有误或按原文无法实现，停止并报告原因，不得静默替换为自己的方案。
遵守计划中的 STOP 条件。计划说遇到 X 就停止，就必须停止，即使自认为能继续推进。
无复现则无修复。如果无法写出因该 bug 而失败的测试，就不要用正常路径测试来提交投机性修复，而应报告“needs repro”。仅因新 API 尚不存在而失败的测试不算失败测试。
绝不提交到 main。先建分支（<type>/<short-slug>，如 fix/3741-turbopack-reexport）。每个分支每个 PR 只处理一个工作项。
如实报告。测试失败就带输出说明；跳过了某个验证门禁就说明是哪个及原因。绝不把未验证的工作描述为已完成。

工作流程

阶段 0 — 理解

端到端阅读计划文件，包括其验证门禁和 STOP 条件。用 gh issue view / gh pr view --comments 阅读关联的 issue/PR；报告者的复现是测试的基础，需获取任何关联的 CodeSandbox/StackBlitz。若无法获得复现且计划中也没有，停止并询问（规则 3）。运行 git log --grep="<keyword>" --oneline -- <relevant-files>，因为 bug 可能已被修复，或先前提交可能揭示根因。阅读 CLAUDE.md 的“Writing Tests”“Fixing Issues from Bug Reports”“Code Style”章节，这些规则完全适用，不再重复。

阶段 1 — 先写失败测试

在实现之前写测试，并观察它因正确原因失败（即 bug 或缺失行为，而非拼写错误或缺失导入）。按 CLAUDE.md 选择层级：纯逻辑用 Jest；涉及 opacity、transform、scroll、布局动画、WAAPI 或视觉行为的用 Cypress（JSDOM 没有 WAAPI，Jest 测试通过不代表“已经可用”）。对于功能，失败测试断言计划验收标准中描述的新行为。

阶段 2 — 实现

做能让测试通过的最小改动，同时匹配周围代码风格。该库会发布给最终用户，需优先考虑小的输出体积。从仓库根目录构建（yarn build），绝不在包内部构建。若计划指定了文件和方案，遵循它们；偏离必须在 PR 描述中明确列出并附一行理由。

阶段 3 — 验证

运行计划指定的每个门禁。计划未说明时的默认项：从根目录运行 yarn build，然后运行相关 Jest 套件；针对 React 18 和 React 19 运行新增/变更的 Cypress 测试，使用 CLAUDE.md 中的 direct-Vite 配方（绝不用 start-server-and-test + turbo），两者都必须通过，特定版本失败是需要调查的发现而非跳过；对触及的包运行 yarn lint。仅忽略 CLAUDE.md/memory 中列出的既有已知失败（SSR TextEncoder、use-velocity）。

阶段 4 — 交付与记录

提交信息需引用 issue/计划（Fix #3741: …）。推送并用 gh pr create 开启 PR，关联 issue（Fixes #<n>），并总结：根因、方案、新增测试、运行的门禁及结果、与计划的偏离。不要使用 gh pr edit，它在该仓库已知损坏（Projects Classic 弃用）。若 gh pr create 成功即完成，不要重试或绕过 edit 失败。更新计划状态：在相关 plans/**/README.md 表格中设置其行（TODO → DONE，或 BLOCKED 并附一行原因），并在计划文件本身追加简短的“Execution notes”章节：做了什么、PR 编号、计划哪里出错。

处理已开启的 PR

工作项可能是“完成 PR #N”而非“修复 issue #N”。此时：gh pr checkout <number>；若落后于 main 则 rebase，保守解决冲突（PR 未刻意改动的代码优先采用 main 版本）。在动代码前运行 gh pr checks <number> 并阅读失败的 CI 日志——计划应说明阻塞点，需验证是否仍然如此。处理计划中列出的评审意见。推送到同一分支。未经检查将要销毁的 diff，绝不 force-push 覆盖非自己编写的提交。

STOP 条件（始终适用，外加计划自身的）

经过 2–3 次诚实尝试后失败测试仍不失败（无法复现）→ 报告“needs repro”并说明尝试过什么。
计划方案与计划写就后已变更的代码冲突 → 报告冲突，不要即兴设计新方案。
某个验证门禁失败且几次尝试内修复不明显 → 报告失败输出。
改动会以计划未预料到的方式触及 packages/framer-motion/src/projection/ 或 effects/VisualElement 系统 → 停止；这些系统有正在进行的重写。

适用场景与限制

适用于已有明确计划、issue 或 PR 的缺陷修复与功能实现，尤其适合需要先复现再修复、并需运行多版本验证门禁的仓库工作流。限制包括：必须严格遵循计划，不得自行扩大范围；无法复现时不得提交修复；不得直接提交 main；不得使用已知损坏的 gh pr edit；涉及特定内部系统（projection、VisualElement）的改动需停止。