rolemodel-skills

Add Agentation visual feedback toolbar to a project. Use when the user asks to "install Agentation", "add the Agentation toolbar", or "set up visual feedback". Covers Rails apps that bundle with webpack into `app/assets/builds` (the RoleModel default) by adding React as a development-only dependency, plus hosts that already bundle React. The same pattern adapts to other server-rendered hosts, but the snippets are Rails.

Shepherd an already-open pull request to a mergeable state — poll CI, triage review comments, verify each one against the source, push fixes, and keep the branch current. Use when the user asks to "babysit", "monitor", "watch", "shepherd", or "drive" a PR, asks you to "fix the CI on my PR", "handle the review comments", "get this PR green", or "wait for checks and address feedback". Picks up where the `create-pr` skill leaves off. Does not approve, merge, or close anything.

Expert guidance for writing, refactoring, and structuring CSS using BEM (Block Element Modifier) methodology. Provides proper CSS class naming conventions, component structure, and Optics design system integration for maintainable, scalable stylesheets.

Use this skill to guide a developer or designer through a BRAVE framework breakdown of a task before they start work. Trigger whenever someone wants to think through a ticket, break down a card, plan their approach before starting, validate a task before picking it up, or prepare a breakdown to share with a teammate or client. Also trigger for any of these phrases or close variations: "BRAVE this", "brave it", "break down this card", "think through this ticket", "help me plan this out before I start", "want to make sure I understand this before I start coding", "want to revalidate this card", "help me think through this before my standup/meeting", or "I'm about to pick up a card and want to break it down". If someone mentions starting work on a card and wants help planning, validating, or understanding it first — this skill should run.

Expose locally-running apps to stable public HTTPS URLs using a single per-developer Cloudflare Tunnel (cloudflared). Use whenever you need an external service to reach your local dev server — receiving webhooks (Box, Stripe, GitHub, Twilio, etc.), testing OAuth callbacks, sharing a work-in-progress with a teammate, or previewing on a real device. Also use when the user mentions cloudflared, "tunnel", "trycloudflare", "public URL for localhost", "webhook can't reach my machine", or asks how to route a domain to their local port.

Opens pull requests with a consistent description format and assignment. Use when the user asks to open, create, file, or draft a PR or pull request, push a branch for review, or write a PR description.

Group all open Dependabot PRs on a repository into a single ordered stack using gh-stack. Run weekly, after Dependabot's batch of grouped-update PRs lands. Use when asked to stack, organize, or clean up Dependabot PRs.

Generate multi-audience documentation from any codebase — workflows for non-technical readers, architecture for developers, and AI orientation for agents. Deterministic JS scripts handle structural extraction; the agent writes the prose. Project-agnostic and self-orienting. Use when the user asks to "document this project", runs `/document-this`, runs `/document-this <file-path>`, runs `/document-this --focus "<Feature Name>"` for a deep-dive on one subsystem in a named subfolder, or wants fresh documentation reflecting the current codebase state.

Build forms that change as they are filled in — cascading or dependent dropdowns, conditional fields and sections, option lists that depend on another field, STI type switches — with the turbo_form gem. Use when a form must update without a full page reload, when adding or changing a dynamic form, or when touching existing `turbo_fetch` routes, actions, or `turbo-form`/`turbo-fetch` Stimulus wiring.

Reviews a PR, commit, range, or branch as a feature first and code second, in a local HTML page whose comments post back to the PR as one GitHub review. Use when the user asks to review a PR or commit, review the feature or shape of a change, or re-review a PR after new pushes: "review PR #123", "review this commit", "review the feature in PR #123", "re-review PR #123".

Interactively fill a project's docs/conventions/ by proposing candidate rules from taste calls, from the codebase, and from past PR review comments, then writing what's confirmed.

Retro on a `make-it-right` run: finds where it missed a problem, kept a false alarm, made a bad fix, or skipped a step, proves each lesson with a failing replay at the lowest level that shows it, and proposes the edit to make-it-right. Also prunes rules that never fire. Use when the user says "made it wrong", "retro make-it-right", "make-it-right missed this", "why didn't make-it-right catch", "the reviewer found what make-it-right didn't", "teach make-it-right", "prune make-it-right", or after a PR that went through make-it-right gets review comments or fix commits.

The optional "make it fast" pass after a change is right. Reviews it for speed and efficiency (database queries, request time, test suite speed, and page responsiveness), verifies each finding, fixes what it can measure, and reports before-and-after numbers. Use when the user says "make it fast", "speed this up", "performance review", "why is this page slow", "check for N+1s", "the specs are slow", or "optimize this", or after `make-it-right` when a change adds or alters queries, endpoints, jobs, spec setup, or markup that loads images, embeds, frames, fonts, or scripts. Skip it for other copy, markup, or style changes: they have nothing to measure.

The "make it right" pass after code works. Tests whether the change meets its requirements and reviews whether it is done correctly, verifies every finding against the source, fixes them, and reports what a human still needs to look at. Use when the user says "make it right", "review and fix", "clean this up before the PR", "get this up to standard", "review my changes", "code review this branch", "is this ready for review", "simplify this", "YAGNI review", or "QA this in the browser".

Styles Rails views with RoleModel's Optics design system — its components, `--op-` design tokens, and theme overrides. Use when writing or reviewing CSS, styling a view or component, picking a color, spacing, font, radius, or shadow value, fixing hard-coded CSS values, adding a project token, or theming an app (brand colors, fonts, color scales, dark mode). Also use when the user says things like "style this", "make this look like the design", "what token should I use", "fix the hard-coded colors", "change the brand color", or "add dark mode".

Serve a child resource that hangs off many different parents — comments, reports, duplications, attachments — from a single Rails controller, using a route concern plus `resource_for` from the rolemodel_rails gem. Use when a child resource needs to attach to several parent models, when about to write a second or third namespaced controller that differs only by its parent (`Articles::CommentsController`, `Widgets::CommentsController`), when a route concern passes a `*_type` route default such as `commentable_type` or `reportable_type`, when a controller looks up its parent with a hard-coded `Parent.find(params[:parent_id])` that now needs to support more parents, or when consolidating duplicated per-parent controllers.

Perform comprehensive code audits of Ruby on Rails applications based on thoughtbot best practices. Use this skill when the user requests a code audit, code review, quality assessment, or analysis of a Rails application. The skill analyzes the entire codebase focusing on testing practices (RSpec), security vulnerabilities, code design (skinny controllers, domain models, PORO with ActiveModel), Rails conventions, database optimization, and Ruby best practices. Outputs a detailed markdown audit report grouped by category (Testing, Security, Models, Controllers, Code Design, Views) with severity levels (Critical, High, Medium, Low) within each category.

RoleModel's Rails conventions where they differ from what an agent writes by default: flash wording, the status for failed saves, Simple Form for every form, how route concerns pass the parent type, and two gotchas (`params.expect` with nested attributes, and Lexxy rich-text change events). Use when writing or reviewing a Rails controller, route, form, or view in a RoleModel app. Also use when the user says things like "add a controller for", "build the form for", "add routes for", "add comments to", "why isn't my nested form saving", or "review this controller".

Find and fix issues from Sentry. Use when asked to fix Sentry errors, debug production issues, investigate exceptions, or resolve bugs reported in Sentry. Methodically analyzes stack traces, breadcrumbs, traces, and context to identify root causes.

Verify what Ruby versions actually exist and install a specific Ruby via rbenv. Use BEFORE asserting that any Ruby version does or doesn't exist (e.g., "Ruby 4.0 isn't out yet", "the latest Ruby is 3.x", "Ruby X.Y.Z doesn't exist"). Also use when the user asks "what's the latest Ruby", "is Ruby X out", "does Ruby X.Y exist", "install Ruby", "switch to Ruby X", "what Ruby is installed", or mentions a specific Ruby version you're unsure about. Claude's training data may be out of date — run `check.sh` first.