/code-scan

Read-only 13-dimension quality analysis. Scores every dimension, computes CODE_SCAN_INDEX, outputs pipeline markers. Makes zero edits.

Target

If a path argument is provided, scan that file/directory. If no argument, scan the code most recently discussed. Multiple paths can be provided to scan a set of components.

Step 0: Load Rubrics

Read .claude/rubric/AUTO-DETECT.md. Follow its instructions:

1. •Always load: base.md + product-quality.md
2. •Auto-detect domain rubrics by checking target files for signals (HTTP server, CLI tool, data persistence, microservice). Load every matching rubric.
3. •Extract Review Criteria sections from each loaded rubric.

If a rubric file doesn't exist, skip it. The generic checklists below are the floor — rubric criteria raise the ceiling.

Record which rubrics were loaded for the summary.

Step 1: Read Target Code

Read ALL files in the target scope completely. Do not skim.

Step 2: Analyze — 13 Dimensions

Evaluate every file against all 13 dimensions. For each finding, assign a severity:

• •Critical (3 pts) — Security vulnerabilities, obvious bugs, data loss risk, >50-line functions, >500-line files
• •Warning (2 pts) — Suboptimal patterns, 25-50 line functions, 300-500 line files, minor clarity issues
• •Observation (1 pt) — Improvement opportunities, style inconsistencies, minor suggestions

Dimension 1: Structure

Generic checklist:

• • Functions ≤25 lines, single responsibility
• • Files ≤300 lines, single responsibility
• • Main entry ≤100 lines
• • Cyclomatic complexity ≤10 per function
• • Nesting depth ≤3
• • Parameters ≤4 per function

Rubric augments: base.md #12 (Architecture), #6 (Bounded Operations)

Dimension 2: Clarity

Generic checklist:

• • Names reveal intent (no abbreviations except standard: API, HTTP, JSON, URL, ID)
• • No comments explaining WHAT — code is self-documenting
• • WHY comments where behavior is non-obvious
• • Boolean variables/params prefixed with is/has/should/can
• • Consistent naming style throughout (camelCase, snake_case, etc.)

Rubric augments: base.md #9 (Structured Logging — naming/context)

Dimension 3: Data Design

Generic checklist:

• • Data structures match the domain
• • No primitive obsession — use value objects / branded types
• • Illegal states unrepresentable (discriminated unions, enums)
• • Immutable by default, mutations explicit and justified
• • Config externalized — no hardcoded URLs, ports, paths, connection strings

Rubric augments: base.md #8 (Config Externalization), product-quality.md #1 (Sensible Defaults)

Dimension 4: Error Handling

Generic checklist:

• • All error paths explicit — no ignored return values
• • No swallowed exceptions or empty catch blocks
• • Cause chains preserved ({ cause: e } or equivalent)
• • Resource cleanup in finally blocks / defer / using
• • Fail fast with actionable messages at boundaries
• • I/O errors handled — no bare file/network calls

Rubric augments: base.md #5 (Error Handling), #7 (Atomic Writes), #10 (Actionable Error Messages); product-quality.md #2 (Interactive Fallbacks), #4 (Error UX); cli.md #1 (if CLI)

Dimension 5: Security

Generic checklist:

• • Input validation at every boundary (API, CLI, file, query)
• • No injection vectors — parameterized queries, safe shell usage
• • No path traversal — paths normalized against a root
• • No secrets in code, logs, error messages, or stack traces
• • No eval(), new Function(), or equivalent dynamic execution
• • Output encoding where applicable

Rubric augments: base.md #1 (Input Validation), #2 (Injection Prevention), #3 (Secret Management), #4 (Auth Lifecycle); web-api.md (if HTTP); cli.md #4 (if CLI)

Dimension 6: Framework Idioms

Generic checklist:

• • Uses built-in solutions before adding dependencies
• • Follows framework conventions and lifecycle patterns
• • No anti-patterns for the detected framework
• • Consistent with framework's error model and async model

Rubric augments: All loaded domain rubrics (web-api.md, cli.md, microservice.md, data-persistence.md)

Dimension 7: Dead Code

Generic checklist:

• • No orphaned files (defined but never imported)
• • No unused exports (exported but never consumed)
• • No unreachable code after return/throw/break
• • No dead branches (conditions always true/false)
• • No commented-out code blocks
• • No unused variables, parameters, or imports

Rubric augments: product-quality.md #3 (No Orphaned Features)

Dimension 8: AI Smells

Generic checklist:

• • No single-use wrapper functions (inline the logic)
• • No comment spam (comments restating what code does)
• • No defensive paranoia (try/catch or null checks for impossible cases)
• • No speculative features (code for requirements that don't exist)
• • No over-abstraction (interfaces/generics with one implementation)
• • No unnecessary type annotations where inference works

Rubric augments: base.md #11 (AI Code Smells)

Dimension 9: Duplication

Generic checklist:

• • No copy-paste blocks (≥5 similar lines across files)
• • No same-name functions with near-identical bodies
• • No repeated validation / guard / boilerplate sequences
• • No duplicated string literals (use constants)
• • No repeated error handling patterns that should be centralized

Rubric augments: (universal — no specific rubric reference)

Dimension 10: Consistency

Generic checklist:

• • Error handling follows one style throughout (throw vs return vs Result)
• • Naming conventions uniform (no mixing camelCase and snake_case)
• • Import style consistent (relative vs alias, order, grouping)
• • Async style consistent (no mixing callbacks, promises, async/await)
• • File organization follows a single pattern

Rubric augments: base.md #9 (Structured Logging — consistent context)

Dimension 11: Type Safety

Generic checklist:

• • No any / object / dynamic / untyped containers where a type is known
• • Type assertions (as) replaced with type guards where possible
• • No implicit type coercion (== instead of ===, string + number)
• • Return types explicit on public functions when not obvious
• • Nullable values handled explicitly (no truthy/falsy shortcuts on non-booleans)

Rubric augments: (generic — domain rubrics add language-specific rules)

Dimension 12: Dependency Health

Generic checklist:

• • No circular imports between modules
• • No unused dependencies in manifest (package.json, requirements.txt, etc.)
• • No deprecated dependencies still in use
• • Lockfile present and committed
• • No vendored copies of available packages

Rubric augments: base.md #13 (Runtime Version)

Dimension 13: Conversion Residue

Generic checklist:

• • No TODO/FIXME comments referencing old frameworks or migrations
• • No stale imports from previous framework/language
• • No foreign idioms (patterns from a different framework used in current one)
• • No dead compatibility shims or polyfills for removed dependencies
• • No mixed old/new API usage where migration should be complete

Rubric augments: Domain rubrics (deviation from expected idiom = residue)

Step 3: Score

Per dimension: Sum finding points (Critical=3, Warning=2, Observation=1), then cap at 10.

dimension_score = min(10, sum_of_finding_points)

A score of 0 = clean, 10 = severe.

CODE_SCAN_INDEX: Sum of all 13 dimension scores. Range 0-130 (lower is better).

CODE_SCAN_INDEX = sum(dimension_scores)  // 0-130

Step 4: Report

Generate the report in this exact structure:

## Code Scan: [target]

### Dimension Heatmap

| # | Dimension | Score | Findings | Worst Issue |
|---|-----------|-------|----------|-------------|
| 1 | Structure | N/10 | Nc Nw No | [brief] |
| 2 | Clarity | N/10 | Nc Nw No | [brief] |
| 3 | Data Design | N/10 | Nc Nw No | [brief] |
| 4 | Error Handling | N/10 | Nc Nw No | [brief] |
| 5 | Security | N/10 | Nc Nw No | [brief] |
| 6 | Framework Idioms | N/10 | Nc Nw No | [brief] |
| 7 | Dead Code | N/10 | Nc Nw No | [brief] |
| 8 | AI Smells | N/10 | Nc Nw No | [brief] |
| 9 | Duplication | N/10 | Nc Nw No | [brief] |
| 10 | Consistency | N/10 | Nc Nw No | [brief] |
| 11 | Type Safety | N/10 | Nc Nw No | [brief] |
| 12 | Dependency Health | N/10 | Nc Nw No | [brief] |
| 13 | Conversion Residue | N/10 | Nc Nw No | [brief] |

Findings column format: `Nc Nw No` = N critical, N warnings, N observations.
Use `—` in Worst Issue for dimensions scoring 0.

### Critical Issues

1. **[file:line]** [Dimension N] — [description]
   - Problem: [what's wrong]
   - Impact: [why it matters]
   - Fix: [how to fix]

### Warnings

1. **[file:line]** [Dimension N] — [description]
   - Concern: [what's questionable]
   - Consider: [improvement]

### Observations

1. **[file:line]** [Dimension N] — [observation]

### Summary

| Metric | Value |
|--------|-------|
| Files scanned | N |
| Total lines | N |
| CODE_SCAN_INDEX | N/130 (Rating) |
| Worst dimension | [name] (N/10) |
| Cleanest dimension | [name] (N/10) |
| Rubrics loaded | base, product-quality[, domain...] |

CODE_SCAN_INDEX: N/130 (Rating)
CODE_SCAN_DONE

Rules

• •READ ONLY — Do not edit any files
• •COMPLETE — Read all target files fully, do not skim
• •SPECIFIC — Cite file:line for every finding
• •ACTIONABLE — Every critical/warning has a fix suggestion
• •NO EXTERNAL TOOLS — Claude analysis only. No Gemini, Codex, Qodana, or MCP tool calls
• •DETERMINISTIC SCORING — Same code, same scores. No rounding, no partial points
• •PIPELINE MARKERS — Always emit CODE_SCAN_INDEX: N/130 (Rating) and CODE_SCAN_DONE at report end