Codebase Inspection Protocol

Codebase Inspection Protocol

Core Rule: "Inspect before you suggest" — No planning decisions without codebase inspection. Every recommendation must cite observed file paths.

Inspection Decision Tree

What are you doing?
│
├─ Creating a new file
│   └─ Inspect: Target directory + similar existing files
│
├─ Implementing a pattern (service, component, job)
│   └─ Inspect: Existing implementations of same pattern
│
├─ Modifying existing code
│   └─ Inspect: All usages + method visibility
│
├─ Making architectural decision
│   └─ Inspect: Project structure + Gemfile + existing patterns
│
└─ Starting fresh on a project
    └─ Run FULL inspection (all sections below)

Quick Inspection Commands

Project Structure

tree app -L 2 -I 'assets|javascript' 2>/dev/null || find app -type d -maxdepth 2
head -60 Gemfile | grep -v '^#' | grep -v '^$'

Pattern Discovery

# Services
ls app/services/*/ 2>/dev/null
head -30 $(find app/services -name '*.rb' | head -1)

# Components
ls app/components/*/ 2>/dev/null
head -40 $(find app/components -name '*_component.rb' | head -1)

# Jobs
ls app/jobs/ 2>/dev/null
head -30 $(find app/jobs -name '*.rb' | head -1)

Naming Conventions

# Class/module patterns in services
grep -r 'module\|class' app/services/ --include='*.rb' | head -20

Method Visibility (Critical!)

# Find method and check if after private/protected
awk '/class/,/private/' app/path/to/file.rb | grep 'def '

NEVER Do This

NEVER suggest a directory structure without checking it exists:

# WRONG: "Let's create app/services/payments/..."
# (Never verified if app/services/ exists or follows different pattern)

# RIGHT: First run: ls app/services/*/ 2>/dev/null
# Then cite: "Following existing pattern in app/services/orders/"

NEVER recommend a pattern without finding an existing example:

# WRONG: "Use the Service Object pattern with .call"
# (Project might use .perform, .execute, or different pattern entirely)

# RIGHT: "Matching TasksManager::Create pattern from app/services/tasks_manager/create.rb"

NEVER assume gem availability:

# WRONG: "Use Sidekiq for this background job"
# (Gemfile might have delayed_job, resque, or good_job instead)

# RIGHT: Check Gemfile first, cite: "Using Sidekiq (Gemfile line 42)"

NEVER invent naming conventions:

# WRONG: "Call it PaymentProcessor" (when project uses PaymentService pattern)
# RIGHT: "Following *Service naming from app/services/order_service.rb"

Inspection Output Template

After inspection, document findings before planning:

## Inspection Findings

### Structure Observed
- Services: `app/services/{domain}/` (namespaced)
- Components: `app/components/{namespace}/` (separate templates)
- Evidence: [file path]

### Pattern in Use
- Service signature: `.call(params)` returns Result object
- Evidence: `app/services/orders/create.rb:15`

### Conventions
- Naming: `{Domain}::{Action}` (e.g., `Orders::Create`)
- Evidence: [file paths showing pattern]

### Dependencies
- Background: Sidekiq (Gemfile:42)
- Components: ViewComponent 3.x (Gemfile:28)

When Inspection Fails

**Inspection Limitation:**
- Unable to access: [path]
- Proceeding with assumption: [assumption]
- Risk: [what could go wrong]
- Mitigation: [how to verify later]

Citation Requirements

Every recommendation must cite:

• Existing patterns: Reference specific file:line
• Similar to X: Show the actual file
• Gem dependencies: Quote the Gemfile line
• Conventions: Show example from codebase

No citations = No recommendation. Return to inspection.