/code-scan

Read-only quality analysis of target code. Identifies problems and improvement opportunities without making any changes.

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 1: Load Expert Context (MANDATORY)

Before scanning, read ALL available expert skills to build your quality lens:

Software Base (always load):

Read: .claude/skills/clarity/SKILL.md        (clear, simple code)
Read: .claude/skills/simplicity/SKILL.md     (small interfaces, composition)
Read: .claude/skills/correctness/SKILL.md    (formal correctness)
Read: .claude/skills/data-first/SKILL.md     (data structures first)
Read: .claude/skills/pragmatism/SKILL.md     (get it working)
Read: .claude/skills/security-mindset/SKILL.md (think like attacker)
Read: .claude/skills/owasp/SKILL.md          (vulnerability patterns)

Domain Profile (load what exists):

Read: .claude/skills/typescript/SKILL.md     (if .ts files)
Read: .claude/skills/react-state/SKILL.md    (if React)
Read: .claude/skills/angular-core/SKILL.md   (if Angular)
Read: .claude/skills/java/SKILL.md           (if Java)
Read: .claude/skills/python-idioms/SKILL.md  (if Python)

Skip files that don't exist. Apply all loaded principles during analysis.

Step 2: Read Target Code

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

Step 3: Analyze (DO NOT EDIT)

Evaluate code against these criteria:

Structure

• • Functions ≤25 lines
• • Files ≤300 lines
• • Main entry ≤100 lines
• • Single responsibility per function
• • Single responsibility per file/module

Clarity

• • Names reveal intent (no abbreviations except standard: API, HTTP, JSON)
• • No comments explaining WHAT (code should be self-documenting)
• • WHY comments where non-obvious
• • Consistent patterns throughout

Data Design

• • Data structures match domain
• • No primitive obsession (use value objects)
• • Illegal states unrepresentable
• • Immutable by default

Error Handling

• • All error paths explicit
• • No swallowed exceptions
• • Fail fast with clear messages
• • No null/undefined leaks

Security (if applicable)

• • Input validation at boundaries
• • No secrets in code
• • Parameterized queries (no string concat)
• • Output encoding

Framework Idioms (based on loaded profile)

• • Follows framework conventions
• • Uses framework patterns correctly
• • No anti-patterns for this framework

Output Format

## Code Scan: [target]

### Summary

| Metric | Value | Status |
|--------|-------|--------|
| Files scanned | N | - |
| Total lines | N | - |
| Largest file | N lines | ⚠️/✓ |
| Largest function | N lines | ⚠️/✓ |
| Critical issues | N | 🔴/✓ |
| Warnings | N | ⚠️/✓ |

### Critical Issues 🔴

Issues that should be fixed:

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

2. ...

### Warnings ⚠️

Issues to consider:

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

2. ...

### Observations 💡

Not problems, but opportunities:

1. **[file]** — [observation]

### Skills Applied

- clarity: [findings summary]
- security-mindset: [findings summary]
- [domain-skill]: [findings summary]

### Files Analyzed

| File | Lines | Functions | Issues |
|------|-------|-----------|--------|
| path/to/file.ts | 245 | 12 | 2 🔴, 1 ⚠️ |
| ... | ... | ... | ... |

Rules

• •READ ONLY - Do not edit any files
• •COMPLETE - Read all files fully, don't skim
• •SPECIFIC - Cite file:line for every issue
• •ACTIONABLE - Every issue has a suggestion
• •PRIORITIZED - Critical vs warning vs observation

What Makes an Issue Critical?

• •Security vulnerabilities
• •Functions >50 lines
• •Files >500 lines
• •Obvious bugs
• •Missing error handling on external calls
• •Framework anti-patterns that cause bugs

What Makes a Warning?

• •Functions 25-50 lines
• •Files 300-500 lines
• •Minor clarity issues
• •Missing documentation on public APIs
• •Suboptimal patterns

Anti-Patterns (Don't Do)

• •Making any edits to files
• •Skimming instead of reading
• •Generic feedback without line numbers
• •Reporting issues without suggestions
• •Missing the security analysis