Plan Tests

Quick Reference

HARD-GATE

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.

Core Process

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.

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. 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.
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. Do not include multiple opening examples unless the user explicitly asks for expanded coverage; list additional cases as follow-up coverage instead.
6. Run and validate: Confirm the failure is because the behavior is missing, not because the setup is broken.
7. Hand off: Continue with write-tests, test-service, test-engine, or the implementation skill that fits the 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

Pitfalls

Extended Resources

Load only when needed:

• assets/first_slice_template.md — Use when producing a complete first-slice decision artifact with boundary table, one opening example, RED proof, follow-up coverage, and HARD-GATE answers.

Output Style

1. Test Proposal: Clearly present the proposed failing spec with the correct boundary context.
2. Opening gate: Include exactly one first failing it example for the initial TDD gate. Put happy path, edge cases, enqueue checks, and validation errors under "Follow-up coverage" unless one of them is the chosen first slice.
3. Failure proof: Show the focused command and the expected RED reason before implementation.
4. Design checkpoint: Answer the four HARD-GATE review questions before handing off.
5. Template use: If the answer needs a full planning artifact, load assets/first_slice_template.md and follow its structure.
6. Language: Must be in English unless explicitly requested otherwise.

Integration

| test-planning-process (from ruby-core-skills) | Process discipline: test type decision framework, coverage strategy |