Inspect

/inspect — Code Quality Inspection

Launch an inspector agent to audit one or more areas of the codebase.

Usage

/inspect <area> [<area> ...] [--json] [--output <path>] [--checks <type1>,<type2>]

Areas can be:

• A file path: /inspect pkg/result/codes.go
• A package: /inspect pkg/engine
• A description: /inspect "error handling across the validation layer"
• Multiple areas: /inspect pkg/result/codes.go pkg/protocol/validation.go

Flags:

• --json — emit structured JSON instead of markdown (machine-readable, enables downstream tooling)
• --output <path> — persist report to disk; path must be under docs/inspections/ or end in -inspection.md / -inspection.json. Example: --output docs/inspections/2026-04-04.md. If omitted, defaults to docs/inspections/<datetime>.md (e.g. docs/inspections/2026-04-11T14-32-00.md).
• --checks <type1>,<type2> — apply only the listed check types, skipping others. Example: --checks dead_symbol,layer_violation
• --consumer-repos <root1>,<root2> — optional comma-separated list of consumer repo absolute paths. Enables cross-repo dead symbol verification: symbols classified as dead locally are checked against consumer repos via mcp__lsp__get_cross_repo_references before being reported. Activates the cross_repo_dead_symbol check type.

What it checks

The inspector applies these checks where relevant — you do not need to specify them:

Check	What it finds
dead_symbol	Defined but never referenced (Tier 1A: mcp__lsp__get_change_impact batch → high confidence; Tier 1B: mcp__lsp__get_references → high confidence; Grep fallback → low confidence)
layer_violation	Import crosses an architectural boundary
scope_analysis	Function or module doing too many things
coverage_gap	Unhandled input, error, or code path
silent_failure	Error suppressed rather than returned
duplicate_semantics	Two symbols that mean the same thing
cross_field_consistency	Related fields with no consistency enforcement
test_coverage	Exported symbol with no test references (Tier 1A: mcp__lsp__get_change_impact test_callers field → more precise than Grep; Tier 1B: mcp__lsp__get_references; Grep fallback)
error_wrapping	Error returned without context (opaque call stack)
doc_drift	Function documentation no longer matches its signature
interface_saturation	Interface with too many methods; callers use a narrow subset
panic_not_recovered	Unhandled crash in a goroutine, thread, or async context
context_propagation	Function receives a context/token but creates a fresh root for callees
init_side_effects	Module initializer performs I/O, network calls, or global mutation

Execution

Launch the inspector agent with the user's areas as input. Pass the current working directory as the repo root. Always set run_in_background: true so the audit runs asynchronously and the user can continue working while it runs.

Pre-flight: warm up LSP and ensure permissions. Background agents cannot receive interactive permission prompts for MCP tools. Two requirements:

1. The user's global settings must include mcp__lsp__* tools in permissions.allow (in ~/.claude/settings.json). Without this, every LSP call from the background agent will be denied silently and the inspector will hang.
2. Call mcp__lsp__start_lsp in the parent session first, then set the gate flag:

# 1. Start LSP in the parent session (prompts once for permission — approve it)
mcp__lsp__start_lsp(root_dir="<repo_root>")

# 2. Set the global ready flag so the inspector gate hook passes for background agents
touch /tmp/.inspector-lsp-global-ready

Launch inspector agent with:
- Areas to inspect: [user's areas]
- Repo root: [resolve the actual repo root from the area path — e.g. if area is /Users/x/code/my-repo/pkg/foo, repo root is /Users/x/code/my-repo]
- Flags: pass through --json, --checks as provided. For --output: if the user provided a path, use it; if omitted, default to `docs/inspections/<YYYY-MM-DDTHH-MM-SS>.md` using the current datetime relative to the repo root
- run_in_background: true
- Instructions: apply the check taxonomy, report findings with severity and file:line citations
- First instruction to agent: DO NOT call mcp__lsp__start_lsp (already running, gate flag is set). Go directly to Step 0 open_document calls, then warm-up check.

Critical: LSP tool usage. Include this instruction verbatim in the inspector agent's launch prompt — the agent definition alone is not sufficient:

LSP enforcement: You have two LSP tool surfaces. Use them in this priority order:

Step 0 — startup sequence (required, do this first, in order):

1. Initialize pointing at the correct repo root (start_lsp is idempotent — safe to call even if already running): mcp__lsp__start_lsp(root_dir="<repo_root>")

2. Open one file per package you plan to audit. gopls does not index a package until at least one file in it is opened. Without this, get_references returns "no package metadata" for all symbols in that package:

   mcp__lsp__open_document(file_path="<repo_root>/internal/lsp/client.go", language_id="go")
   mcp__lsp__open_document(file_path="<repo_root>/internal/tools/workspace.go", language_id="go")
   # … one representative file per package being audited
   

3. Warm-up check (mandatory before trusting zero-reference results): Pick one symbol you know is actively used (e.g. a widely-called function in the first package). Call get_references on it. If it returns [], the workspace is not yet indexed — wait 3–5 seconds and retry. Do not proceed to dead-symbol checks until a known-active symbol returns ≥ 1 reference.

1A. mcp__lsp__get_change_impact (Tier 1A — batch, preferred for dead_symbol and test_coverage): Call once per file; returns all exported symbols with non_test_callers and test_callers counts. Example: mcp__lsp__get_change_impact(changed_files=["/abs/path/file.go"], include_transitive=false) non_test_callers == 0 AND test_callers == 0 → dead. non_test_callers == 0 AND test_callers > 0 → test-only. If unavailable or errors: proceed to Tier 1B.

1B. mcp__lsp__get_references (Tier 1B — per-symbol fallback for dead_symbol): Call this for per-symbol reference lookups. Returns 1-based locations. Example: mcp__lsp__get_references(file_path="/abs/path/file.go", language_id="go", line=22, column=6) Zero results = dead symbol (high confidence). If the call errors, fall back to option 2.

2. LSP built-in tool (fallback or for hover/other operations): Use for hover, go-to-definition, and as fallback when mcp__lsp-mcp is unavailable. LSP(operation="hover", filePath="/abs/path/file.ts", line=14, character=10)

Do NOT shell out to gopls/rust-analyzer/tsserver via Bash. If both LSP surfaces fail, fall back to Grep and annotate as reduced confidence.

The agent works autonomously. When it completes you will be notified — surface the report directly to the user at that point.

JSON output and validation

When --json is passed, the agent emits a structured report conforming to assets/schema.json. To validate a report:

scripts/validate-report report.json
# or: cat report.json | scripts/validate-report

Exit 0 = valid, 1 = schema errors, 2 = usage error.