codebase-inspection_skill

Overview

This skill enforces a mandatory inspection step before proposing or writing any Rails code. It prevents unverified assumptions by requiring concrete file path citations for every recommendation. Use this protocol to keep architectural decisions, naming, and implementations consistent with the existing codebase.

How this skill works

Before any implementation, the skill runs targeted inspections of project folders, example files, and the Gemfile to discover existing patterns and dependencies. It maps observed structures (services, components, jobs), extracts signatures and naming conventions, and produces an Inspection Findings report that cites specific file:line evidence. If inspection cannot access a path, it records limitations and prescribes mitigations rather than guessing.

When to use it

• Starting any implementation task or feature work
• Making architectural or high-level design decisions
• Suggesting patterns, naming, or conventions
• Creating new files, directories, or classes
• Modifying existing code with cross-cutting impact

Best practices

• Always run structure and pattern discovery commands and cite results before planning
• Reference exact file paths and line numbers for examples (e.g., app/services/orders/create.rb:15)
• Verify Gemfile entries before recommending libraries or background adapters
• Search for existing implementations of the same pattern rather than introducing a new one
• Document inspection failures with assumptions, risks, and verifications

Example use cases

• Before adding a payment service: inspect app/services/* and cite similar files like app/services/payments/processor.rb:12
• Choosing a background job adapter: check Gemfile and quote the exact gem line before recommending Sidekiq or GoodJob
• When proposing a naming convention: show examples such as Orders::Create found at app/services/orders/create.rb:10
• Modifying a public method: list all usages and show visibility checks from the target file before changing signatures
• On onboarding a new Rails project: run a full inspection to map structure, patterns, and key dependencies