# Scan

> Run deterministic pattern checks against backend code. Use when you need mechanical detection of known anti-patterns, code smells, or structural issues. Triggers: 'scan code', 'check patterns', 'run checks', or /axiom:scan. Do NOT use for qualitative architecture review — use axiom:critique instead.

- Skill: `lvlup-sw/scan` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lvlup-sw/scan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lvlup-sw/scan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lvlup-sw (https://skillmd.com/u/lvlup-sw)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lvlup-sw/scan

---


# Scan Skill

## Overview

Deterministic check engine that runs grep patterns and structural analysis against backend code. Accepts a `scope` argument (file path, directory path, or cwd) and a `dimensions` argument (comma-separated dimension list or "all") to control which checks execute.

This skill performs purely mechanical detection — it matches known patterns, counts structural violations, and reports findings with exact file locations. It does not make qualitative judgments about architecture or design. Other skills (like `axiom:critique`) handle subjective assessment and invoke `scan` when they need deterministic evidence.

See `@skills/scan/references/check-catalog.md` for scan-specific execution guidance including ordering, batching, and exclusions.

## Triggers

Activate this skill when:
- User says "scan code", "check patterns", "run checks", or "detect anti-patterns"
- User runs `/axiom:scan`
- Another axiom skill requests deterministic pattern detection
- User wants mechanical verification of known code smells

Do not activate this skill when:
- User wants qualitative architecture review — use `axiom:critique` instead
- User wants a full quality audit — use `axiom:audit` instead
- User needs subjective design feedback rather than pattern matching

## Process

### Step 1: Load Check Catalog

Load the canonical check definitions from `@skills/backend-quality/references/deterministic-checks.md`. This file defines every grep pattern, structural check, and their associated dimensions and severities.

### Step 2: Load Project-Specific Checks (Optional)

If `.axiom/checks.md` exists in the project root, load additional project-specific check definitions. These follow the same format as the canonical catalog and are merged into the check set. If the file does not exist, silently skip this step.

### Step 3: Filter by Requested Dimensions

Apply the `dimensions` argument to filter the merged check set:
- If `dimensions` is `"all"` or omitted, run every check in the catalog
- If `dimensions` is a comma-separated list (e.g., `"topology,observability"`), only run checks tagged with those dimensions
- Invalid dimension names produce an actionable error message listing valid dimensions

### Step 4: Execute Checks

For each check in the filtered set, run the grep or structural pattern against the resolved `scope`:
- Execute grep patterns using the exact expressions from the catalog
- Run structural analysis checks (file counts, nesting depth, import graphs)
- Collect all matches with file path, line number, and matched content
- Record checks that produced zero matches as passing

### Step 5: Format Findings

Format each match as a finding per `@skills/backend-quality/references/findings-format.md`. Every finding produced by this skill is marked `deterministic: true` to distinguish mechanical detections from qualitative assessments.

### Step 6: Group and Output

Output findings grouped by dimension, then by severity (HIGH, MEDIUM, LOW) within each dimension. Include:
- Total checks run and total findings
- Per-dimension summary with finding counts
- Individual findings with file location, matched pattern, and remediation hint

## Error Handling

- **Invalid patterns:** If a grep pattern from the catalog fails to compile or execute, report the specific pattern and error message. Do not silently skip — the user needs to know which check is broken so they can fix the catalog entry.
- **Empty scope:** If the resolved scope contains no files to scan (empty directory, nonexistent path), return a "nothing to scan" message with the resolved path. Do not treat this as a failure.
- **Missing `.axiom/checks.md`:** Silently skip project-specific check loading. This file is optional and its absence is expected for projects that have not customized their check set.
- **Permission errors:** If a file cannot be read due to permissions, log the file path and continue scanning remaining files.

## Output Format

All findings use the standard format from `@skills/backend-quality/references/findings-format.md` with one addition: every finding includes `deterministic: true` to signal that it was produced by mechanical pattern matching, not qualitative judgment.

```yaml
dimension: observability
severity: MEDIUM
deterministic: true
file: src/handlers/query.ts
line: 42
pattern: readEvents
match: "const items = await readEvents(stream)"
remediation: "Move raw event reads out of query handlers — use a read model projection instead"
```

## Anti-Patterns

| Don't | Do Instead |
|-------|------------|
| Make qualitative judgments about matches | Report the match and let critique/review skills interpret |
| Skip checks that produce many matches | Report all matches — downstream skills handle prioritization |
| Suppress false positives silently | Report them and let the user tune exclusions in `.axiom/checks.md` |
| Run checks outside the requested scope | Respect the scope boundary strictly |
| Invent patterns not in the catalog | Only run checks defined in the canonical or project-specific catalogs |