rails-bug-triage

Rails Bug Triage

当存在 Bug 报告，但尚不明确正确的复现路径和修复顺序时，使用此技能。

核心原则： 不要猜测修复方法。先复现 Bug，选择正确的失败测试，然后规划最小且安全的修复。

流程

1. 记录报告： 重述预期行为、实际行为和复现步骤。
2. 界定范围： 判断问题出现在请求处理、领域逻辑、作业、引擎集成还是外部依赖中。
3. 收集当前证据： 日志、错误消息、边缘情况输入、近期变更或缺失的保护措施。
4. 选择第一个失败的测试： 选择用户或运维人员能观察到 Bug 的边界。
5. 确定最小修复路径： 指明可能涉及的文件，以及能让测试通过的最小行为变更。
6. 交接： 继续使用 rails-tdd-slices -> rspec-best-practices -> 实现技能。

分诊输出

按以下格式返回调查结果：

1. 观察到的行为
2. 预期行为
3. 可能的边界
4. 要添加的第一个失败测试
5. 最小且安全的修复路径
6. 后续技能

示例（状态码错误 Bug）：

1. Observed:  POST /orders returns 500 when product is out of stock
2. Expected:  Returns 422 with { error: "Out of stock" }
3. Boundary:  Request layer — visible in HTTP contract
4. First spec: spec/requests/orders/create_spec.rb
5. Fix path:  Orders::CreateOrder should return { success: false, error: "Out of stock" }
              when inventory check fails; controller renders 422
6. Next:      rails-tdd-slices → write request spec → rspec-best-practices → fix

失败测试骨架：

# spec/requests/orders/create_spec.rb
RSpec.describe "POST /orders", type: :request do
  context "when product is out of stock" do
    let(:product) { create(:product, stock: 0) }

    it "returns 422 with an error message" do
      post orders_path, params: { order: { product_id: product.id, quantity: 1 } }, as: :json
      expect(response).to have_http_status(:unprocessable_entity)
      expect(response.parsed_body["error"]).to eq("Out of stock")
    end
  end
end

在实现修复前运行：bundle exec rspec spec/requests/orders/create_spec.rb

边界指南

完整的 Bug 类型 → 测试类型映射和分层诊断技巧，请参阅 BOUNDARY_GUIDE.md。

快速参考：

Bug 类型	可能的首个测试
HTTP 现象（状态码、JSON、重定向）	请求测试
数据现象（值错误、验证）	模型或服务测试
时序现象（缺少作业、邮件）	作业测试
引擎路由/生成器回归	dummy app 中的引擎测试

注意事项

易犯问题	应对方法
Bug 在请求层可见，却使用单元测试	从实际观察到故障的地方着手
将复现、重构和新功能捆绑在一起	仅通过最小且安全的切片修复 Bug
将不稳定的证据当作可以开始修补的信号	修改代码前先稳定复现过程
解释中依赖“可能”或“也许”	存在歧义，说明复现步骤尚未完成

集成

技能	适用场景
rails-tdd-slices	为 Bug 选择最有力的首个失败测试
rspec-best-practices	选择测试后，正确执行 TDD 循环
refactor-safely	Bug 位于高风险重构区域，且必须先保留现有行为时
rails-code-review	检查最终 Bug 修复是否存在回归或覆盖缺失
rails-architecture-review	Bug 暴露出更深层的边界或编排问题时

资源

• assets/examples.md