name: 系统化修复缺陷 description: 通过系统化调查、根因分析和针对性验证来诊断和修复缺陷。在出现故障、错误、性能下降或意外行为时使用。

系统化修复缺陷

用于隔离根因并在现有功能中实施针对性修复的结构化协议。

何时使用

出现故障需要诊断和修复时
发生错误消息或意外行为时
现有功能出现性能下降时
出现间歇性或难以复现的问题时

核心步骤

1. 上下文与复现

阅读相关文档：

docs/feature-spec/F-##-*.md 用于受影响功能
docs/user-stories/US-###-*.md 用于预期行为和验收标准
docs/api-contracts.yaml 如果与API相关
docs/system-design.md 用于架构上下文

记录缺陷：

预期行为（引用故事验收标准或规范）
实际行为（故障表现）
复现步骤
功能ID (F-##) 和 故事ID (US-###)（如果已知）

2. 调查

简单缺陷（明显入口点）

使用直接调查：

使用grep定位错误消息或相关代码
阅读疑似文件检查实现
跟踪函数调用和数据转换
检查相关文件中的关联逻辑

复杂缺陷（多个子系统或不清晰来源）

并行委托给异步代理：

生成 senior-engineer 代理以：

通过特定子系统跟踪错误流
分析相关失败模式
调查运行时条件

生成 Explore 代理以：

跨多个文件映射数据流
查找特定操作的所有错误处理
定位配置和集成点

示例： 对于身份验证缺陷，生成：

代理1：“从登录端点到会话创建跟踪身份验证流”
代理2：“在身份验证模块中找到所有错误处理和验证”
代理3：“定位会话存储配置和相关代码”

使用 ./agent-responses/await {agent_id} 等待结果

3. 根因分析

生成假设：

从调查中列出3-8个潜在根因
根据概率（代码证据）和影响排名
选择最可能的原因

决策点：

立即修复 如果根因明显且确认
添加验证 如果存在多个合理原因或运行时依赖行为

4. 验证（如果需要）

添加最小调试：

在决策点记录日志
在边界检查数据
在集成点记录输入/输出

在修复前测试以确认根因。

5. 实施

修复已确认的根因：

保持更改最小化且专注
除非批准，否则保持API稳定性
遵循代码库中的现有模式

如果需要，更新文档：

在功能规范或变更日志中添加备注
如果合约更改，更新 docs/api-contracts.yaml（需要批准）
对于斜杠命令：
- /manage-project/update/update-feature 以更正规范
- /manage-project/update/update-story 如果验收标准不明确
- /manage-project/update/update-api 如果API更改（需要批准）

6. 验证与测试

针对验收标准验证修复：

测试受影响用户故事的所有验收标准
检查1-2个关键边缘情况和错误状态
如果API更改，运行合约测试
验证 docs/data-plan.md 中的事件仍正确触发

7. 清理

删除所有调试和日志代码
确认没有临时文件残留

调查策略

对于直接调查：

使用grep、read_file 理解子系统
手动通过相关文件跟踪流
关注缺陷表现的特定区域

何时在修复前验证：

存在多个合理根因时
运行时依赖行为时
间歇性或难以复现的问题时

对于异步调查：

每个代理调查独立子系统
并行运行以提高速度
最多6个代理（收益递减）

工件

输入：

docs/feature-spec/F-##-*.md — 功能规范
docs/user-stories/US-###-*.md — 预期行为和验收标准
docs/api-contracts.yaml — API规范
docs/system-design.md — 架构上下文

输出：

调查发现（内联备注或代理报告）
更新后的功能规范，带缺陷解决备注
修复后的代码及伴随测试

快速参考

场景	方法
单一子系统，明显入口	直接调查 → 立即修复
多个子系统，来源不清晰	并行生成2-4个代理 → 综合发现 → 修复
运行时依赖或间歇性	添加针对性日志 → 复现 → 分析日志 → 修复
需要多个独立修复	通过工件文件将调查结果传递给修复代理