rails-tdd-loop

Rails TDD Loop — Complete Feature Workflow

Workflow Phases

Phase 1: Context & Test Design

1. skills/context/rails-context-engineering — Load schema, routes, nearest patterns (ensures context matches codebase)
2. skills/testing/rails-tdd-slices — Choose the correct first failing spec (model→model spec, API→request, UI+DB→system)
3. skills/testing/rspec-best-practices — Write the test and verify it FAILS (use let/build, confirm failure is for missing feature)

HARD GATE — Test Feedback Checkpoint:

• Test EXISTS (written and saved)
• Test has been RUN
• Test FAILS for the correct reason (feature missing, not typo/config)

Failure type	Example	Action
Correct	undefined method 'full_name'	Proceed to implementation
Incorrect	syntax error, factory not registered	Return to rspec-best-practices

If test feedback is NOT OK: Return to rspec-best-practices and refine.

---

Phase 2: Implementation

1. Implementation Proposal Checkpoint — Propose approach (example: "User#full_name: concatenate first_name + last_name with space")

2. User confirms approach — Wait for explicit approval

3. Implement minimal code to pass the test (single method, no premature abstractions, simplest thing that works)

4. Verify test passes — Run the spec again:

   bundle exec rspec spec/path/to/your_spec.rb
   

If test does NOT pass: Return to implementation (minimal changes, re-verify).

---

Phase 3: Iterate (Optional)

Check: More behaviors to implement?

• Yes: Return to Phase 1 (rspec-best-practices) for next behavior
• No: Proceed to Phase 4

---

Phase 4: Finish

1. Linters + Full Test Suite:

   bundle exec rubocop
   bundle exec brakeman --no-pager
   bundle exec rspec
   

2. skills/patterns/yard-documentation — Document public Ruby API (code documentation)
3. skills/code-quality/rails-code-review — Self-review the PR (quality assurance)
4. Open PR — Feature complete

---

Integration

Workflow complete → PR ready. Bug mid-implementation → skills/testing/rails-bug-triage. Security/architecture concerns → skills/code-quality/rails-security-review / skills/code-quality/rails-architecture-review.

---

Example

Inline example with file structure:

spec/models/user_spec.rb:

RSpec.describe User do
  describe '#full_name' do
    let(:user) { build(:user, first_name: 'John', last_name: 'Doe') }
    it 'concatenates first and last name' do
      expect(user.full_name).to eq('John Doe')
    end
  end
end

app/models/user.rb:

def full_name
  "#{first_name} #{last_name}"
end

See assets/example.md for complete end-to-end walkthrough with commands and phases.