Codebase Inspection Protocol Skill
This skill provides mandatory inspection procedures that MUST be followed before any code generation or architectural decisions in a Rails project.
When to Use This Skill
-
ALWAYS before writing any new code
-
Before making architectural decisions
-
Before suggesting any pattern
-
When assumptions are made about existing code
-
Before creating any new file
Core Rule
"Inspect before you suggest"
No planning decisions without codebase inspection. Every recommendation must cite observed file paths. Never assume a pattern exists—verify it first.
Mandatory Inspection Checks
- Project Structure
Primary structure check
tree app -L 2 -I 'assets|javascript' 2>/dev/null || find app -type d -maxdepth 2
List all app directories
ls -la app/*/ 2>/dev/null
Count Ruby files
find app -type f -name '*.rb' | wc -l
Answers: What is the current project structure?
- Existing Patterns
Check for services directory
ls app/services/ 2>/dev/null || echo 'No services directory'
Check for service subdirectories (namespace pattern)
ls app/services/*/ 2>/dev/null || echo 'No service subdirectories'
Find service classes
grep -r 'class.Service' app/ --include='.rb' -l 2>/dev/null | head -10
Find command classes
grep -r 'class.Command' app/ --include='.rb' -l 2>/dev/null | head -5
Find query objects
grep -r 'class.Query' app/ --include='.rb' -l 2>/dev/null | head -5
Answers: What patterns are already in use?
- Naming Conventions
Sample a service file
head -30 $(find app/services -name '*.rb' 2>/dev/null | head -1) 2>/dev/null || echo 'No service files'
Sample a model file
head -30 $(find app/models -name '*.rb' 2>/dev/null | head -1) 2>/dev/null
List module/class definitions in services
grep -r 'module|class' app/services/ --include='*.rb' 2>/dev/null | head -20
Answers: What naming and style conventions exist?
- Dependencies
Check Gemfile
cat Gemfile 2>/dev/null | grep -v '^#' | grep -v '^$' | head -60
Check Ruby version
cat Gemfile.lock 2>/dev/null | grep -A1 'RUBY VERSION' || ruby -v
Check Rails configuration
cat config/application.rb 2>/dev/null | head -40
Answers: What gems and tools are available?
- Models and Domain
List models
ls app/models/ 2>/dev/null
Find models with associations
grep -l 'has_many|belongs_to|has_one' app/models/*.rb 2>/dev/null | head -10
Sample a model file
head -50 $(find app/models -name '*.rb' 2>/dev/null | head -1) 2>/dev/null
Check schema
head -100 db/schema.rb 2>/dev/null
Answers: What is the domain model structure?
- Testing Patterns
Check test directory structure
ls spec/ 2>/dev/null || ls test/ 2>/dev/null || echo 'No test directory found'
Check spec helper
cat spec/spec_helper.rb 2>/dev/null | head -30 || cat spec/rails_helper.rb 2>/dev/null | head -30
Check for service specs
ls spec/services/ 2>/dev/null || echo 'No service specs'
Answers: What testing conventions are in place?
Contextual Checks
When Creating a New File
Check target directory
ls {target_directory}/ 2>/dev/null
Sample existing files in target
find {target_directory} -name '*.rb' -exec head -20 {} ; 2>/dev/null | head -60
When Implementing a Pattern
Search for existing implementations
grep -r '{pattern_name}' app/ --include='*.rb' -l 2>/dev/null
Find files with pattern name
find app -name '{pattern_name}' -type f 2>/dev/null
When Modifying Existing Functionality
Find all usages
grep -r '{class_name}' app/ --include='*.rb' -B2 -A5 2>/dev/null
Find method calls
grep -r '{method_name}' app/ --include='*.rb' 2>/dev/null
When Working with ViewComponents
Check components directory
ls app/components/ 2>/dev/null
Check component namespaces
ls app/components/*/ 2>/dev/null
Sample existing component
head -40 $(find app/components -name '*_component.rb' | head -1) 2>/dev/null
Check for inline vs file templates
grep -l 'def call' app/components/**/*_component.rb 2>/dev/null | head -3
Check template files
ls app/components/**/*.html.erb 2>/dev/null | head -10
When Working with Controllers
List controllers
ls app/controllers/ 2>/dev/null
Check controller namespaces
ls app/controllers/*/ 2>/dev/null
Sample a controller
head -50 $(find app/controllers -name '*_controller.rb' | head -1) 2>/dev/null
Check routes
rails routes 2>/dev/null | head -50 || cat config/routes.rb | head -50
When Working with Background Jobs
Check jobs directory
ls app/jobs/ 2>/dev/null || ls app/sidekiq/ 2>/dev/null
Sample a job
head -30 $(find app/jobs -name '*.rb' | head -1) 2>/dev/null
Check Sidekiq configuration
cat config/sidekiq.yml 2>/dev/null
Method Visibility Inspection
When checking if methods can be called across layers:
Find method definition with context
grep -B10 'def method_name' app/path/to/file.rb
Check for private/protected keywords before method
grep -n 'private|protected' app/path/to/file.rb
List all public methods (before private keyword)
awk '/class/,/private/' app/path/to/file.rb | grep 'def '
Inspection Output Format
After running inspection, document findings:
Inspection Findings
Project Structure
- Services:
app/services/with subdirectories for namespacing - Components:
app/components/with namespace folders - Models: Standard Rails structure in
app/models/
Existing Patterns Observed
- Services follow:
{Domain}Manager::{Action}pattern - Example:
app/services/tasks_manager/create_task.rb - Components use separate template files (not inline)
Naming Conventions
- Services:
TasksManager::CreateTask - Components:
Metrics::KpiCardComponent - Models: Standard ActiveRecord naming
Dependencies Available
- Ruby 3.3.0
- Rails 7.1.0
- ViewComponent 3.x
- Sidekiq for background jobs
Testing Structure
- RSpec in
spec/ - FactoryBot for fixtures
- Service specs in
spec/services/
Anti-Pattern Detection
Planning Without Inspection
Detection: Plan outputs lack file path citations
Example Violation:
"Let's create a service in app/services/..." (without checking if directory exists or pattern already in use)
Assumption-Based Design
Examples:
-
Suggesting Service Objects without checking if app/services/ exists
-
Recommending a gem without checking Gemfile
-
Proposing a naming convention different from existing code
-
Assuming Rails version without checking
Blind Scaffolding
Detection: Code doesn't reference or match existing patterns
Consequence: Review existing similar files first
Convention Invention
Detection: New naming pattern, structure, or style not present in codebase
Consequence: Either match existing convention or explicitly justify deviation
Inspection Failure Handling
When inspection commands fail:
Inspection Limitation:
- Unable to access: [path/file]
- Reason: [error message]
- Proceeding with assumption: [assumption]
- Risk: [potential issues if assumption is wrong]
Quick Reference Commands
Project structure
tree app -L 2 -I 'assets|javascript'
Services
ls app/services/ 2>/dev/null
Patterns
grep -r 'class.Service' app/ --include='.rb' -l | head -10
Gems
cat Gemfile | grep -v '^#' | grep -v '^$'
Models
ls app/models/
Style sample
head -30 $(find app/services -name '*.rb' | head -1)
Components
ls app/components/ 2>/dev/null
Component pattern
head -40 $(find app/components -name '*_component.rb' | head -1)
Schema
head -100 db/schema.rb
Must Cite
When making any recommendation, cite evidence:
-
Existing patterns: Reference specific file paths
-
"Similar to X" references: Show the actual file
-
Gemfile dependencies: Quote the gem line
-
Existing conventions: Show example from codebase