rails-cto doctor

rails-cto doctor is a read-only drift detector. It checks that every config file the gem installed is still present, still matches the bundled template, and still contains the settings the skills depend on. It doesn't modify anything — if it finds a problem, it tells you and you decide whether to re-run init with --force or fix the file by hand.

Usage

bundle exec rails-cto doctor

Run it:

• After upgrading the gem, to catch new template changes
• Before a release, to confirm the quality gates are still wired
• When a skill starts misbehaving, to rule out a config issue

What it checks

Config file presence

For each file the gem installs, doctor verifies that the file exists at its expected path:

• .rubocop.yml
• .reek.yml
• .bundler-audit.yml
• config/brakeman.yml
• .herb/rewriters/align-attributes.mjs
• .herb/rules/no-inline-styles.mjs

Missing files are reported as errors — the corresponding skill won't work without them.

Template drift

For each installed file, doctor compares the contents against the bundled template. Any difference is reported as drift.

Drift is not automatically an error. You may have intentionally customized a file. But the report lets you see what drifted, which is useful when:

• A new gem version ships with new template content you might want
• You inherited a project and need to know which files were edited after install
• A skill is failing and you suspect a config regression

Gemfile entries

doctor verifies that your Gemfile includes all the toolchain gems the skills depend on — RuboCop (with Rails + Minitest cops), Reek, Flog, Flay, Brakeman, bundler-audit, SimpleCov with the JSON formatter, and Herb. Missing gems are reported as errors.

SimpleCov patch

doctor checks that test/test_helper.rb boots SimpleCov with the JSON formatter. If the block is missing or uses a different formatter, the QA skill's coverage check will fail — so this is reported as an error.

CLAUDE.md block

doctor checks that your project's CLAUDE.md contains the RailsCTO skills block. Without it, the mandatory skills (/rails-cto, /rails-cto-qa, /rails-cto-erb, /rails-cto-tailwind) won't fire automatically. Missing block is reported as a warning — the plugin will still work if you invoke skills manually, but you lose the automatic enforcement.

Interpreting the output

doctor groups findings into three levels:

• OK — the file or setting is present and matches expectations
• Warning — something's missing that reduces automatic enforcement but doesn't break anything
• Error — something's missing that will cause a skill to fail

If you see errors, the fastest fix is usually:

bundle exec rails-cto init --force

That overwrites drifted files with the bundled templates and re-adds anything that was deleted. See rails-cto init for details.

If you see warnings and want to keep your customizations, leave them as they are — doctor is informational.