Codebase Inspection Protocol

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

1. 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?

2. 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?

3. 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?

4. 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?

5. 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?

6. 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