Deterministic Checks
Overview
A shell script that scans a repository for five specific, mechanically-detectable problems and reports file:line locations. Zero model cost — it never asks a model to "be careful" about something a regex can already prove.
Core principle: If a check can be regex or wc -c, it should never be a paragraph of instructions asking the model to look carefully. Reserve judgment calls for the model; hand mechanical checks to the script.
What it checks
| Check | Catches | Misses (by design) |
|---|---|---|
| Conflict markers | <<<<<<<, =======, >>>>>>> at line start | Markers inside a fenced code block that's documenting conflict markers (a known false-positive class — see below) |
| Live-looking credentials | AWS keys, GitHub tokens, PEM private keys, sk--style API keys | Anything not matching those four shapes — this is not a general secret scanner |
| Debug leftovers | console.log/console.debug, debugger;, pdb.set_trace(), binding.pry in JS/TS/Python/Go/Ruby files | Debug prints in languages/patterns not listed |
| Untracked TODO/FIXME | TODO/FIXME/XXX with no #123 or TICKET-123 reference nearby | TODOs that reference a ticket — those are considered tracked |
| Oversized files | Any file over 5MB, excluding lockfiles and .min.js | Nothing — this one has no heuristic gap |
Usage
bashbash ${CLAUDE_SKILL_DIR}/scripts/scan.sh [path] # defaults to .
Exit code 0 = clean, 1 = findings printed to stdout, 2 = usage error. In a Git repo it scans tracked + untracked-but-not-ignored files (via git ls-files); outside Git it walks the filesystem, skipping node_modules, .git, .claude/worktrees, dist, build, and vendor.
Set SCAN_NO_GIT=1 when project policy forbids even read-only Git commands. The script then uses the filesystem walk regardless of repository state:
bashSCAN_NO_GIT=1 bash ${CLAUDE_SKILL_DIR}/scripts/scan.sh .
Excluding a path (e.g. a docs file that intentionally shows conflict-marker syntax):
bashSCAN_EXCLUDE='path/to/docs-with-examples\.md' bash ${CLAUDE_SKILL_DIR}/scripts/scan.sh .
SCAN_EXCLUDE is a grep -Ev pattern matched against each file path.
Known false-positive class
Any file that documents these patterns — a git tutorial showing <<<<<<< HEAD, a security post pasting a fake AKIA... example, this skill's own README — will trigger a match. The script cannot distinguish "this is a real conflict" from "this is prose about conflicts" with a line-oriented regex. When a finding is a documentation example, exclude that path with SCAN_EXCLUDE rather than trying to make the regex smarter — a regex that understands fenced-code-block context is not worth the fragility it adds. This is the same trade every pre-commit secret scanner makes.
When to use vs. when not to
Use before: committing, opening a PR, reporting "done" on a task that touched files, merging a branch.
Don't use for: language-specific type checking, style/formatting (use the project's linter), security review beyond the four credential shapes above (use agents/security-audit-prompt.md for judgment-requiring review), or as a substitute for tests.
Wiring it as a hook instead of running it manually
This is also usable as a Stop hook so it runs automatically instead of you remembering to invoke it — see the hooks/hooks.json pattern in agents/hooks-automation-prompt.md. A Stop hook that exits 1 blocks the turn from ending until the findings are addressed or explicitly accepted.
Remember
This script proves the absence of five specific problems. It proves nothing else. Don't report "clean" as "reviewed" — it's a floor, not a review.
