rails-bug-triage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rails Bug Triage

Rails Bug 分诊排查

Use this skill when a bug report exists but the right reproduction path and fix sequence are not yet clear.

Core principle: Do not guess at fixes. Reproduce the bug, choose the right failing spec, then plan the smallest safe repair.

当已有bug报告，但尚未明确正确的复现路径和修复步骤时，可使用此技能。

核心原则： 不要猜测修复方案。先复现bug，选择合适的失败测试用例，再规划最安全的最小化修复方案。

Process

流程

Capture the report: Restate the expected behavior, actual behavior, and reproduction steps.
Bound the scope: Identify whether the issue appears in request handling, domain logic, jobs, engine integration, or an external dependency.
Gather current evidence: Logs, error messages, edge-case inputs, recent changes, or missing guards.
Choose the first failing spec: Pick the boundary where the bug is visible to users or operators.
Define the smallest fix path: Name the likely files and the narrowest behavior change that should make the spec pass.
Hand off: Continue through
```
rails-tdd-slices
```
->
```
rspec-best-practices
```
-> implementation skill.

记录报告： 重述预期行为、实际行为以及复现步骤。
界定范围： 确定问题是否出现在请求处理、领域逻辑、任务（jobs）、引擎集成或外部依赖中。
收集现有证据： 日志、错误信息、边缘情况输入、最近的代码变更或缺失的防护逻辑。
选择首个失败测试用例： 选择bug对用户或运维人员可见的边界点。
定义最小修复路径： 指出可能涉及的文件，以及能让测试用例通过的最细微行为变更。
后续流转： 按照
```
rails-tdd-slices
```
→
```
rspec-best-practices
```
→ 实现技能的流程推进。

Triage Output

排查输出

Return findings in this shape:

Observed behavior
Expected behavior
Likely boundary
First failing spec to add
Smallest safe fix path
Follow-up skills

Example (wrong status code 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

Skeleton failing spec:

ruby

undefined

请按以下格式返回排查结果：

实际观察到的行为
预期行为
可能的边界层
需添加的首个失败测试用例
最安全的最小修复路径
后续技能

示例（错误状态码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

失败测试用例模板：

ruby

undefined

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


Run it before implementing the fix: `bundle exec rspec 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`

Boundary Guide

边界层指南

See BOUNDARY_GUIDE.md for the full bug-shape → spec-type mapping and layer diagnosis tips.

Quick reference:

Bug shape	Likely first spec
HTTP symptoms (status, JSON, redirect)	Request spec
Data symptoms (wrong value, validation)	Model or service spec
Timing symptoms (missing job, email)	Job spec
Engine routing/generator regression	Engine spec in dummy app

完整的bug类型→测试用例类型映射以及层诊断技巧，请查看BOUNDARY_GUIDE.md。

快速参考：

Bug类型	推荐的首个测试用例
HTTP症状（状态码、JSON、重定向）	Request spec
数据症状（值错误、验证失败）	Model or service spec
时序症状（任务丢失、邮件未发送）	Job spec
引擎路由/生成器回归问题	Engine spec in dummy app

Pitfalls

常见误区

Pitfall	What to do
Unit spec when the bug is visible at request level	Start where the failure is actually observed
Bundling reproduction, refactor, and new features	Fix the bug in the smallest safe slice only
Flaky evidence treated as green light to patch	Stabilize reproduction before touching code
The explanation relies on "probably" or "maybe"	Ambiguity means the reproduction step isn't done yet

误区	解决办法
当bug在请求层可见时却使用单元测试用例	从实际观察到失败的层级开始
将复现、重构和新功能混在一起	仅在最安全的最小范围内修复bug
将不可靠的证据作为修复依据	在修改代码前先稳定复现问题
解释中使用“可能”“大概”等模糊表述	模糊性说明复现步骤尚未完成

Integration

技能集成

Skill	When to chain
rails-tdd-slices	To choose the strongest first failing spec for the bug
rspec-best-practices	To run the TDD loop correctly after the spec is chosen
refactor-safely	When the bug sits inside a risky refactor area and behavior must be preserved first
rails-code-review	To review the final bug fix for regressions and missing coverage
rails-architecture-review	When the bug points to a deeper boundary or orchestration problem

技能	何时衔接
rails-tdd-slices	为bug选择最适合的首个失败测试用例时
rspec-best-practices	选定测试用例后正确执行TDD循环时
refactor-safely	当bug位于高风险重构区域，且需先保留现有行为时
rails-code-review	审查最终bug修复是否存在回归问题和测试覆盖缺失时
rails-architecture-review	当bug指向更深层次的边界或编排问题时