vanilla-rails-work-breakdown

ZempTime's avatarfrom ZempTime

Use when planning Rails features or breaking down work into PRs - enforces 2-5 file PRs, bug fix separation, and one-sentence scope test

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 26, 2025
[Code Review]

When & Why to Use This Skill

This Claude skill streamlines the Ruby on Rails development workflow by enforcing a disciplined approach to Pull Requests (PRs). It focuses on breaking down complex features into small, atomic PRs (ideally 2-5 files) that pass the 'one-sentence scope test.' By strictly separating concerns—such as keeping bug fixes, styling, and refactoring in independent PRs—it minimizes review friction, reduces merge conflicts, and ensures a clean, readable project history based on industry-leading standards like those used by 37signals.

Use Cases

  • Feature Decomposition: Use this skill when starting a new Rails feature to map out a sequence of small, manageable PRs that follow logical grouping rules (e.g., Model + Tests together, but Sorting separate).
  • PR Scope Validation: Apply the 'One Sentence Test' to your current work-in-progress to determine if a PR is becoming too bloated or needs to be split before submission.
  • Emergency Bug Handling: Follow the skill's protocol when a bug is discovered mid-feature to ensure the fix is branched, tested, and merged independently of the new feature code.
  • Standardizing Commit Messages: Generate and enforce concise, present-tense commit messages that improve repository maintainability and team communication.
namevanilla-rails-work-breakdown
descriptionUse when planning Rails features or breaking down work into PRs - enforces 2-5 file PRs, bug fix separation, and one-sentence scope test

Vanilla Rails Work Breakdown

Core Rule

Each PR = one sentence. Target 2-5 files, max 7-8.

If you can't describe the PR in one sentence, split it.

CRITICAL: If your PR description uses "and", STOP and split it.

Bundle Together

  • Model + tests (but NOT scopes/sorting)
  • Controller + view + tests
  • Migration + model using it
  • Routes + controller they configure

Tests go with the functional change, never with styling.

Keep Separate (ALWAYS)

Each of these MUST be its own PR:

  • Bug fixes
  • Refactoring
  • Styling/CSS (even one line)
  • Filters (even simple params)
  • Sort options (including scopes like pinned_first)

Example: Card Pinning

Wrong (3 PRs):

  1. "Add pinning to cards with sorting" (model + sorting scope + tests)
  2. "Add UI for pinning" (controller + views + tests)
  3. "Add filtering and styling" (filter + CSS)

Right (5 PRs):

  1. "Add pinning to cards" (migration + model methods + tests, 3 files)
  2. "Add UI for pinning cards" (controller + view + tests, 4 files)
  3. "Sort pinned cards first" (scope + tests, 2 files)
  4. "Add filter for pinned cards" (controller param + view + tests, 3 files)
  5. "Style pinned cards" (CSS, 1 file)

Commit Messages

Present tense, no prefixes:

Add hotkeys for triaging cards
Fix HTML injection in webhook titles
Expose card ID on comments

Not: feat:, fix:, WIP:

Red Flags

Stop and split if:

  • More than 7-8 files
  • PR title has "and"
  • Mixing refactoring with features
  • Bug fix included with feature

Bug During Feature Work

  1. Branch from main for bug fix
  2. Fix + test in separate PR
  3. Return to feature branch
  4. Rebase after bug fix merges

Never bundle bug fixes with feature PRs.

One Sentence Test

✅ "This PR adds pinning to cards" ❌ "This PR adds pinning, styling, and filters"

If you use "and", split the PR.

Common Rationalizations (STOP)

Excuse Reality
"Sorting is part of the model concern" No. Sorting is a feature that ships separately. Core pinning works without sorting.
"Styling and filtering touch the same view" Different concerns. Filtering is functional, styling is visual. Separate PRs.
"More efficient to bundle them" 37signals values small PRs over efficiency. 2-5 files is the target.
"They're logically grouped" "Logical grouping" is not the test. One sentence without "and" is the test.
"Just a few lines of CSS" Styling ALWAYS separate. Even one line.
"Just a tiny partial" View code goes with controller, not model. Size irrelevant.
"It's related functionality" Each feature = one PR. Even if related. One sentence test applies.
"The change is trivial" Size doesn't matter. Separate concerns = separate PRs.