bug-intake

<p>bug-intake 是一个面向单个 Bug 报告的处理技能，其核心目标是将一条故障描述系统性地转化为可验证的修复过程。它不属于需求规格阶段，不进行访谈或制定计划，可能完全没有规格文档。</p><h3>用途与流程</h3><p>该技能覆盖从捕获报告到修复验证的完整链路，主要分为八个阶段：捕获、分诊、查找契约、复现、根因分析、路线选择、编写报告、执行修复。</p><ul><li><b>捕获</b>：用报告者的原话记录发生了什么、期望什么、发生在哪个分支或提交、环境与关键配置。只询问复现所需且缺失的信息；无人值守运行时将假设记录为 Q- 条目。</li><li><b>分诊</b>：阅读报告与相关代码但不做任何变更（不改文件、测试或分支）。输出严重程度（红/橙/黄，结合影响与可能性）、所属领域（如数据、后端、前端、产品）、跨越的架构层（每层附文件:行号）、Bug 类型（代码 Bug、数据 Bug、需求缺失、接口问题、遗留代码、性能等）。同时指出代码能确认、反驳或尚无法检查的部分。</li><li><b>查找契约</b>：按顺序查找期望行为的来源：功能规格的验收标准、决策记录、已发布的契约或项目文档（OpenAPI、JSON schema、CLI 帮助、README 等）、现有测试与同类代码、报告者的期望。记录使用的来源并指出缺口。若无来源决定行为，则需做出决策，选择与同类代码和公开契约一致的选项，写入假定契约；仅在不可逆或会被质疑时记录 ADR。</li><li><b>复现</b>：编写最小的自动化失败测试，放在用户遇到 Bug 的层（API 响应用 HTTP 测试，查询用单元测试），运行并确认因报告原因而失败。脚本仅用于探索，修复从测试开始。若两次诚实尝试后仍无法复现，停止并走路线 D。</li><li><b>根因分析</b>：从入口点沿代码路径追踪到出错行。用 grep 查找所有调用者和同模式代码（相同解析器、未检查的请求体、相同查询）。若兄弟代码共享原因，在共享点修复。同原因兄弟代码在范围内，途中发现的其他 Bug 单独列为报告行。</li><li><b>路线选择</b>：根据复现与根因更新分诊灯色。路线 A：存在契约且代码违反；路线 B：无契约或契约错误/沉默，先写契约再修复；路线 C：报告要求未承诺的行为，走功能交付流程；路线 D：无法复现或原因为环境/配置，停止并报告。</li><li><b>编写报告</b>：保存为 .scratchpad/<slug>/bug-report.md，使用对话语言，包含报告、分诊、契约、复现、根因、范围等章节，以及灯色、所属领域、类型、路线、发现位置等表格。</li><li><b>修复路线</b>：创建 fix/<slug> 分支，按变更列表模式执行计划循环，第一项为带修复的失败测试，每个同原因兄弟代码单独为一项。根据风险等级执行检查：黄色仅回归测试与全量测试；橙色增加受影响标准或契约验证；红色增加红队评审与浏览器验收测试。回归测试永不跳过。然后编写视觉 PR 和会话回顾。</li></ul><h3>适用场景</h3><p>适用于软件开发或维护过程中收到具体 Bug 报告后，需要系统化地进行分诊、复现、定位与修复的场合，尤其适合希望将每个 Bug 转化为可追溯的测试和修复记录的团队。</p><h3>限制</h3><p>资料未提供安装命令、调用方式、收费模式、平台支持等具体信息。该技能假设项目有代码库、测试框架和版本控制，且依赖其他技能（如 git-commit-organizer、execute-plan-loop、write-visual-pr 等）配合完成修复流程。</p>