Implement

Git Sync Gate (mandatory)

All work happens directly on the main branch. No feature branches.

GIT-1. Before starting any work, sync with remote:

git checkout main
git pull origin main

If there are uncommitted local changes, stash or commit them first.

GIT-2. After validation passes (Phase 4), stage, commit, and push:

git add -A
git commit -m "implement: <description of the implementation>"
git push origin main

Phase 1: Context & Regression-Aware Baseline

1. Treat any text supplied after the skill invocation as the active feature scope, failing spec target, or green-phase context.
2. Check for pending migrations before running specs — bin/rails db:migrate:status. Pending migrations are a common cause of false failures.
3. Assess current cycle position and regression baseline: confirm which specs are currently failing and verify they fail for the right reason (missing implementation, not setup issues). If specs fail for setup reasons, fix those first. If a previously-green behavior regressed, restore that baseline before expanding scope.
4. If the work touches views, components, helpers, presenters, CSS, Stimulus, user-facing copy, or page structure, also read docs/ui_guidelines.md, docs/behance_product_ui_system.md, and docs/references/behance/ai_voice_generator_reference.md before implementing.

Commands

Run Tests

• All specs: bundle exec rspec
• Specific file: bundle exec rspec spec/path/to_spec.rb
• Specific line: bundle exec rspec spec/path/to_spec.rb:25
• Detailed format: bundle exec rspec --format documentation spec/path/to_spec.rb
• Fail fast: bundle exec rspec --fail-fast
• Only failures: bundle exec rspec --only-failures

Lint

• Auto-fix: bundle exec rubocop -a
• Specific path: bundle exec rubocop -a app/models/

Console

• Rails console: bin/rails console (test implementation manually)

Phase 2: Analyze Failing Tests & Implement

Step 1: Analyze Failing Tests

Read the failing test output to understand:

• What functionality is being tested?
• What type of implementation is needed?
• Which layers of the application are involved?

Step 2: Implement by Layer

Based on the failing tests, implement changes in dependency order:

1. Database first: Migration → Model
2. Business logic second: Service → Query
3. Application layer third: Controller → Policy
4. Presentation last: Presenter → ViewComponent → Stimulus

Database Changes

If tests fail because tables, columns, or constraints don't exist: → Create safe, reversible migrations with proper indexes and constraints.

Model Implementation

If tests fail for model validations, associations, scopes, or methods: → Implement the ActiveRecord model. Keep models focused on data and persistence, not business logic.

Business Logic

If tests fail for complex business rules, calculations, or multi-step operations: → Implement service objects following SOLID principles with Result objects for success/failure handling. Follow Resumes::Bootstrapper, Admin::SettingsUpdateService patterns.

Authorization

If tests fail for permission checks or access control: → Implement Pundit policy rules following principle of least privilege.

Controller/Endpoints

If tests fail for HTTP requests, responses, or routing: → Create thin controllers that delegate to services and ensure proper authorization. Use controller_message(...) for flash copy backed by I18n.

UI Components

If tests fail for view rendering or component behavior: → Implement ViewComponents reusing shared Ui::* components, ui_* helper APIs, and atelier-* tokens.

Presenters

If tests fail for view logic or data formatting: → Implement *State presenters wired through helpers with memoization. Follow Resumes::TemplatePickerState, ResumeBuilder::EditorState patterns.

Complex Forms

If tests fail for multi-step forms or form objects: → Implement form objects handling multi-model forms with consistent validation and transactions.

Background Jobs

If tests fail for asynchronous processing or scheduled tasks: → Create idempotent jobs with proper retry logic using Solid Queue.

Email Notifications

If tests fail for email delivery or mailer logic: → Implement mailers with both HTML and text templates and previews.

Turbo Features

If tests fail for Turbo Frames, Turbo Streams, or Turbo Drive: → Implement using HTML-over-the-wire approach with frames, streams, and morphing.

Stimulus Controllers

If tests fail for JavaScript interactions or frontend controllers: → Create accessible Stimulus controllers with proper ARIA attributes and keyboard navigation.

Complex Queries

If tests fail for database queries, joins, or aggregations: → Create optimized query objects with N+1 prevention using includes/preload.

Phase 3: Project-Specific Implementation Patterns

Follow established project patterns during implementation:

• Controllers: thin, HTTP-only — delegate to services/presenters
• Services: call interface, single responsibility
• Presenters: *State classes wired through helpers with memoization. Include I18n.locale in memoization keys when locale-sensitive.
• UI baseline: reuse shared Ui::* components before introducing page-local visual wrappers
• I18n: all user-visible copy via I18n.t(...) in the correct domain-scoped locale file. Quote YAML "on"/"off" keys. Never use titleize/humanize for display labels.
• Seeds: update db/seeds.rb when new models, templates, feature flags, or demo data paths are introduced
• Locale files: config/locales/views/resumes.en.yml (resume-side), resume_builder.en.yml (builder), templates.en.yml (marketplace), admin.en.yml (admin), public_auth.en.yml (public/auth), config/locales/en.yml (shared catalog labels)

Watch for common pitfalls:

• Stale cached associations — reload or look up by ID when needed (e.g., photo_profile pattern)
• Active Storage jobs polluting enqueued_jobs — use clear_enqueued_jobs after asset setup in specs
• Locale namespace drift between resume_builder.* and resumes.* keys — verify the view's t(...) calls match the loaded locale file

Phase 4: Validate

1. Run targeted specs: bundle exec rspec <affected_spec_files>
2. Run ruby -c syntax checks on modified Ruby files
3. Run YAML parse checks on modified locale files
4. Regression check: after the targeted specs pass, run any adjacent spec files that exercise the same controllers, services, or models to confirm no regressions.
5. Update only the files needed for the green phase and avoid speculative refactors.

After ALL tests pass:

• Run full test suite: bundle exec rspec
• Run linter: bundle exec rubocop -a
• Report completion

Phase 5: Re-assess & Cycle Forward

Re-assess the affected area after validation: note any remaining failing specs, adjacent behavior that now needs a Red phase, or coverage gaps revealed by the Green implementation.

Next steps:

• When targeted tests pass → recommend /rspec to assess coverage gaps or refactor phase
• If all specs are green and no refactoring needed → recommend /rspec to assess coverage gaps
• For the next behavior slice → recommend writing more failing tests (RED phase), then re-run /implement

Full TDD cycle chain: Red → Green (/implement) → Refactor → Re-assess coverage (/rspec) → back to Red for the next behavior slice. Each skill feeds into the next in a continuous loop.

Green Phase Philosophy

Minimal Implementation

Only implement what the test explicitly requires:

• Test validates presence of name? → Add validates :name, presence: true
• Test checks price is positive? → Add validates :price, numericality: { greater_than: 0 }
• Don't add validations that tests don't require

YAGNI (You Aren't Gonna Need It)

• Don't add features "just in case"
• Don't over-optimize prematurely
• Don't add complexity before it's needed
• Trust the tests to drive the design

Simple Solutions First

• Use Rails conventions
• Prefer built-in Rails methods
• Avoid custom code when framework provides it
• Extract complexity only when tests demand it

Code Standards

Naming Conventions

• Models: Product, OrderItem (singular, PascalCase)
• Controllers: ProductsController (plural, PascalCase)
• Services: Products::CreateService (namespaced, PascalCase)
• Policies: ProductPolicy (singular, PascalCase)
• Jobs: ProcessPaymentJob (descriptive, PascalCase)
• Specs: product_spec.rb (matches file being tested)

File Organization

app/
├── models/
│   └── product.rb
├── services/
│   └── products/
│       ├── create_service.rb
│       └── update_service.rb
├── policies/
│   └── product_policy.rb
└── controllers/
    └── products_controller.rb

Success Criteria

You succeed when:

1. ✅ All tests pass (GREEN)
2. ✅ Implementation is minimal (YAGNI)
3. ✅ Code follows Rails conventions
4. ✅ Rubocop passes
5. ✅ Each layer handled with appropriate patterns

Boundaries

• ✅ Always: Run tests after each implementation, implement minimal solution
• ⚠️ Ask first: Before adding features not required by the tests
• 🚫 Never: Modify test files, over-engineer solutions, skip running tests after changes

Anti-Patterns to Avoid

• ❌ Implementing features not required by tests
• ❌ Writing tests yourself (tests are already written in the RED phase)
• ❌ Over-engineering solutions
• ❌ Not running tests after each change
• ❌ Modifying tests to make them pass

Remember

• Your goal: Make tests pass with minimal code
• Your principle: YAGNI — You Aren't Gonna Need It
• Your output: GREEN tests, nothing more

The next phase (Refactor) will improve the code structure. Your job is to make tests pass, not to make code perfect.