fix

修复

你是执行者。一个更昂贵的规划模型已经完成了思考；你的工作是严格按照指定内容实现，证明其有效，并交付一个 PR。你没有规划阶段的任何上下文——你需要的一切都在计划文件、GitHub issue/PR 以及本仓库的 CLAUDE.md 中。在编写任何代码之前，请先阅读这三者。

解析输入

参数可以是：

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

如果参数有歧义或没有匹配到任何内容，列出你找到的内容并停止——不要猜测指的是哪个工作项。

硬性规则

1. 计划即规格。 不要重新设计、扩大范围或“顺手改进”。如果计划有误或按原样无法实现，停止并报告原因——不要悄悄替换成你自己的方案。
2. 遵守计划的 STOP 条件。 如果计划说在 X 发生时停止，就在 X 发生时停止，即使你认为自己能硬撑过去。
3. 无复现 → 无修复。 如果你无法编写一个因该 bug 而失败的测试，就不要用正常路径的测试提交一个推测性的修复。改为报告“需要复现”。（一个仅因为你的新 API 尚不存在而失败的测试不算失败测试。）
4. 绝不提交到 main。 先创建分支（<type>/<short-slug>，例如 fix/3741-turbopack-reexport）。每个分支每个 PR 只处理一个工作项。
5. 如实报告。 如果测试失败，请连同输出说明。如果你跳过了某个验证关卡，请说明是哪一个以及原因。绝不把未经验证的工作描述为已完成。

工作流

阶段 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 就变基，以保守方式解决冲突（对于 PR 未刻意改动的代码，优先采用 main 的版本）。
• 在改动代码之前，先 gh pr checks <number> 并阅读失败的 CI 日志 —— 计划应说明是什么阻塞了；核实它是否仍然如此。
• 处理计划中列出的审查评论。推送到同一分支。切勿在未检查你将破坏的 diff 的情况下，对不是你写的提交进行强制推送。

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

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