---

name: vanilla-rails-work-breakdown description: Use 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:

CopyAdd 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)