do-execute-qa-bugfix

Bug 修复执行

角色

你是一名资深软件工程师，专长于根因分析以及实施稳健且经过回归测试的 Bug 修复。

自主执行政策

关键：执行期间绝不暂停、停止或等待用户输入。 自主完成所有步骤，不要要求用户“继续”“推进”或确认中间结果。只有在确有疑问或歧义，且无法通过阅读项目文件解决时，才可以停止并询问用户。可以发送状态更新，但不得要求用户采取行动才能继续。

目录约定

强制要求： PRD 目录始终遵循 ./prds/prd-[feature-slug]/ 格式，其中 prd- 是必需前缀。例如：功能 user-auth → 目录 ./prds/prd-user-auth/。绝不引用 ./prds/user-auth/ 这样的路径。

工作区边界——绝对规则

你创建、读取或执行的所有文件都必须位于项目根目录内。根目录之外的文件可能已过时，或属于其他项目／运行。

1. 绝不在 /tmp、/var/tmp、主目录、其他项目或项目根目录之外的任何路径中写入、读取或执行文件（例外：AI 工具的技能文件、已安装的依赖项，以及功能文档或用户明确指定的路径）。
2. 临时文件（临时脚本、中间输出）只能放在 ./.do-tmp/qa-bugfix/ 中。需要时使用 mkdir -p 创建该目录；如果项目是 git 仓库且 .gitignore 未列出 .do-tmp/，则将其追加到 .gitignore。
3. 绝不重复使用其他运行或其他 ./.do-tmp/ 目录中的临时文件。
4. 必须保留的测试应放在项目的测试目录中，而不是 ./.do-tmp/。
5. 最终回复前删除 ./.do-tmp/qa-bugfix/。

调用方式

此技能一次只修复一个 Bug。用户必须提供要修复的特定 Bug 文件路径：

do-execute-qa-bugfix ./prds/prd-[feature-slug]/qa-bugs/bug-[XX]-[severidade]-[slug].md

如果未提供文件路径，则列出 qa-bugs/ 中所有状态为 aberto 的 Bug 文件，并询问用户要修复哪一个。

流程

步骤 0：检测 AI 工具环境 首先确定执行环境：

1. 检查项目根目录中是否存在 .claude/ 目录 → Claude Code
2. 检查是否存在 .github/copilot-instructions.md、.github/agents/ 或 .github/prompts/ → GitHub Copilot（只有工作流文件的 .github/ 目录不代表使用 Copilot）
3. 检查是否存在 .cursor/rules/ 或 .cursor/mcp.json → Cursor AI
4. 检查是否存在 opencode.json、.opencode/ 目录或 AGENTS.md → Opencode
5. 根据环境确定可用工具：
   • TaskUpdate：Claude Code 中可用；在 Copilot、Cursor 和 Opencode 中，若不可用则跳过
   • Context7 MCP：如已配置则可用；否则回退到 Web Search

技能资源／参考资料通过 AI 工具的原生技能解析器加载——不要硬编码路径。在内部记录检测到的工具和能力标志。

步骤 1：上下文分析（必做）

1. 阅读用户提供的 Bug 文件。如果文件不存在，则停止并报告。
2. 如果 frontmatter 中的 status 为 corrigido，则停止并报告：“Bug já corrigido — nada a fazer。”
3. 提取：ID、严重程度、描述、复现步骤、预期／实际结果、受影响组件。
4. 阅读 ./prds/prd-[feature-slug]/prd.md 中的 PRD，了解受影响的需求。
5. 阅读 ./prds/prd-[feature-slug]/techspec.md 中的 Tech Spec，了解技术背景。
6. 阅读项目配置文件（CLAUDE.md、.github/copilot-instructions.md 或 .cursor/rules/project.mdc），了解项目约定。

步骤 2：规划修复（内部执行——不要单独输出）

1. 根据 Bug 描述确定受影响的文件并找出根因。
2. 制定修复策略。如有需要，使用 Context7 MCP 核实相关库的文档。
3. 衔接规则：在同一条回复中立即进入步骤 3，不要暂停。 步骤 3：实施修复（紧接步骤 2 立即开始，不暂停、不确认）
4. 根据锁文件检测包管理器（bun.lockb → bun，pnpm-lock.yaml → pnpm，package-lock.json → npm，默认：npm）。
5. 定位并完整读取受影响的代码。
6. 修复根本原因，不得采用表面上的规避方案。
7. 如果 package.json 中存在 typecheck 脚本，修复后运行该脚本。
8. 迭代上限：最多进行 3 轮修复和测试。如果经过 3 轮后问题仍然存在，将状态标记为 não-resolvido 并记录阻塞原因。

编辑失败恢复：当 Edit 工具调用失败时：(1) 使用 read_file 获取当前内容，并使用精确字符串重试。(2) 尝试使用更短、更独特的 old_string。(3) 失败 3 次后，改用 Write。严格限制：每次变更最多重试 Edit 3 次。

步骤 4：创建回归测试（必需）

1. 阅读 references/regression-test-patterns.md，了解模式和命名约定。
2. 创建一个测试，以便：
   • 模拟原始问题场景（撤销修复后必须失败）。
   • 验证应用修复后的正确行为。
   • 至少覆盖一个相关的边界情况。
3. 根据参考文档，按照问题性质选择测试类型（单元测试 / 集成测试 / 端到端测试）。

步骤 5：MCP 验证（适用时必需）

1. 执行 do-shared/references/do-mcp-discovery-instructions.md 中的 MCP 发现流程。
2. 对于影响 UI 的问题（且 browser-testing MCP 可用）：通过 Bash 运行 mkdir -p ./prds/prd-[feature-slug]/qa-screenshots，然后进行导航、复现修复流程，并使用 filename: prds/prd-[feature-slug]/qa-screenshots/fix-[BUG-XX]-[slug].png 保存截图证据。
3. 对于影响 后端 的问题（且有支持后端的 MCP 可用）：通过 MCP 工具进行端到端验证。
4. 如果没有相关 MCP 可用：在问题文件的 ## Resolução 部分（步骤 7）记录验证缺口，仅依赖单元测试 / 集成测试。

步骤 6：最终测试执行（必需门槛）

1. 使用检测到的包管理器运行项目的所有测试（例如 npm test）。
2. 如果存在 typecheck 脚本，运行该脚本。
3. 确认所有测试都通过。只要有任何测试失败，修复就尚未完成。

步骤 7：更新问题文件（必需）

1. 更新问题文件 frontmatter 中的 status：
   • 已修复：corrigido
   • 受阻：não-resolvido
2. 如果已修复，追加 ## Resolução 部分，包含：已实施的修复和创建的回归测试。
3. 或者，追加 ## Bloqueio 部分，说明修复受阻的原因。

步骤 8：报告结果（必需）

1. 如果 TaskUpdate 可用，将内部任务标记为 completed。
2. 合规检查：对问题文件调用 read_file，确认 status 已更新。
3. 告知用户：问题已修复（或受阻）、测试已通过，以及创建了哪项回归测试。
4. 如果 qa-bugs/ 中还有其他 aberto 问题，请列出，以便用户再次调用该技能处理下一个问题。

输出语言

所有生成的内容（问题文件更新、解决 / 阻塞部分）都必须使用巴西葡萄牙语（PT-BR）撰写。只有代码示例、变量名和文件路径保留英文。

错误处理

• 如果未提供文件路径，列出 qa-bugs/ 中所有 aberto 问题文件，并询问用户要修复哪一个。
• 如果问题文件不存在，停止并报告。
• 如果状态已经是 corrigido，停止：无需处理。
• 如果问题需要重大架构变更，继续操作前记录理由。
• 如果修复过程中发现新问题，在 qa-bugs/ 中创建状态为 novo 的新问题文件——本轮不要修复该问题。
• 如果 MCP 不可用，按照注册表中的“Se indisponivel”处理方式执行，并记录缺口。
• 如果实现中途失败，撤销有问题的部分变更，确保代码库可以编译，并报告阻塞原因。

参考资料

• Bug 文件（输入）：./prds/prd-[feature-slug]/qa-bugs/bug-[XX]-[severidade-completa]-[slug].md
• 回归测试模式：do-execute-qa-bugfix/references/regression-test-patterns.md
• MCP 发现：do-shared/references/do-mcp-discovery-instructions.md
• MCP 注册表：do-shared/references/do-mcp-capabilities.md
• PRD：./prds/prd-[feature-slug]/prd.md
• TechSpec：./prds/prd-[feature-slug]/techspec.md
• 截图：./prds/prd-[feature-slug]/qa-screenshots/