Rails TDD Slices

Use this skill when the hardest part of the task is deciding where TDD should start.

Core principle: Start at the highest-value boundary that proves the behavior with the least unnecessary setup.

Quick Reference

HARD-GATE

DO NOT choose the first spec based on convenience alone.
DO NOT start with a lower-level unit if the real risk is request, job, engine, or persistence wiring.
ALWAYS run the chosen spec and verify it fails for the right reason before implementation.

When to Use

• The user asks where to start TDD for a Rails change.
• A feature spans multiple layers and the first spec is not obvious.
• A bug is reproducible but it is unclear whether to begin with request, service, model, or job coverage.
• Next step: Chain to rspec-best-practices after choosing the slice, then to the implementation skill for the affected area.

Process

1. Name the behavior: State the user-visible outcome or invariant to prove.
2. Locate the boundary: Decide where the behavior is observed first: HTTP request, service entry point, model rule, job execution, engine integration, or external adapter.
3. Pick the smallest strong slice: Choose the spec type that proves the behavior without dragging in unrelated layers.
4. Suggest the path: Name the likely spec path using normal Rails conventions (for example spec/requests/..., spec/services/..., spec/jobs/..., spec/models/...).
5. Write one failing example: Keep it minimal; one example is enough to open the gate.
6. Run and validate: Confirm the failure is because the behavior is missing, not because the setup is broken.
7. Hand off: Continue with rspec-best-practices, rspec-service-testing, rails-engine-testing, or the implementation skill that fits the slice.

Decision Heuristics

Rails Paths

Use conventional spec paths when recommending the first slice:

Examples

Good: New JSON Endpoint

# Behavior: POST /orders validates params and returns 201 with JSON payload
# First slice: request spec
# Suggested path: spec/requests/orders/create_spec.rb

RSpec.describe "POST /orders", type: :request do
  let(:user) { create(:user) }
  let(:valid_params) { { order: { product_id: create(:product).id, quantity: 1 } } }

  before { sign_in user }

  it "creates an order and returns 201" do
    post orders_path, params: valid_params, as: :json
    expect(response).to have_http_status(:created)
    expect(response.parsed_body["id"]).to be_present
  end
end

Good: New Orchestration Service

# Behavior: Orders::CreateOrder validates inventory, persists, and enqueues follow-up work
# First slice: service spec
# Suggested path: spec/services/orders/create_order_spec.rb

RSpec.describe Orders::CreateOrder do
  subject(:result) { described_class.call(user: user, product: product, quantity: 1) }

  let(:user)    { create(:user) }
  let(:product) { create(:product, stock: 5) }

  it "returns a successful result with the new order" do
    expect(result).to be_success
    expect(result.order).to be_persisted
  end
end

Bad: Starting Too Low

# Bad first move:
# Start with a PORO helper spec because it is easier to write,
# even though the real risk is the request contract or workflow wiring.

Test Feedback Checkpoint

After writing and running the first failing spec, pause before implementation and present the test for review:

CHECKPOINT: Test Design Review

1. Present: Show the failing spec(s) written
2. Ask:
   - Does this test cover the right behavior?
   - Is the boundary correct (request vs service vs model)?
   - Are the most important edge cases represented?
   - Is the failure reason correct (feature missing, not setup error)?
3. Confirm: Only proceed to implementation once test design is approved.

Why this matters: Implementing against a poorly designed test wastes the TDD cycle. A 2-minute review of the test now prevents a full rewrite later.

Hand off: After test design is confirmed → rspec-best-practices for the full TDD gate cycle.

Output Style

When using this skill, return:

1. Behavior to prove
2. Chosen boundary
3. First spec type
4. Suggested spec path
5. Why this is the highest-value starting slice
6. Next skill to chain

Common Mistakes

Red Flags

• "We'll add the request spec later"
• The chosen spec cannot prove the user-visible behavior
• The first spec requires excessive factories just to boot
• The failure is caused by broken setup rather than missing behavior
• The first recommendation is a controller spec without a repo-specific reason
• A system spec is chosen even though a request or service spec would prove the behavior faster

Integration