code-evaluator

name

code-evaluator

description

Evaluate code to prevent common AI coding mistakes — dead code, duplication, complexity hotspots, reinvented helpers, leftover scaffolding. Two functions plus a pre-write advisor. Use after writing or editing code, when asked to review code quality, clean up the codebase, find unused code, find duplicates, check complexity, or evaluate what an AI just wrote. Commands: review (post-write), sweep (full codebase).

Code Evaluator

Prevents and removes the mistakes an AI coder commonly makes. Language-agnostic: uses ripgrep + native tools, no compiled analyzer required. Grounded in a strict safety model — grep proposes candidates, the compiler and the test suite decide.

Commands

Command	Layer	Action
/code-evaluator review [path]	L2 (post-write)	Evaluate a diff or path just written; tier findings; apply only HIGH-confidence, guard-cleared fixes
/code-evaluator sweep	L3 (full codebase)	Whole-tree dead-code / duplication / complexity / over-engineering report (report-only at scale)

A third layer (L1, pre-write) is the code-design-advisor agent, spawned by other skills at non-obvious code decisions (wired in by /skill-builder route). It is not a user command — it advises before code is written.

When to Use

• Right after writing or editing code (the review reflex).
• When asked to clean up a codebase, find unused/dead code, find duplicates, or check complexity (sweep).
• When another skill is about to make a non-obvious code decision (the advisor).

When NOT to Use

• Style/formatting (use the project's linter/formatter).
• Type errors (use the type checker).
• Verified security scanning (use a SAST tool).

Workflow

Model-Lane Preflight

CHECKPOINT — Model-Lane Preflight Gate (slim, advisory-only; fires at the TOP of this skill's workflow, before any generative step):

1. SKIP silently IF ANY of: /route dispatched this invocation after running its own lane preflight (a lane advisory OR ask already printed, route otherwise ASSESSED the lane this turn, or it was deliberately suppressed — route's coverage extends to the whole endeavor whether route asked, matched, or the user declined, including skills this one chains); this skill's frontmatter sets model-lane-gate: off; the session is headless / non-interactive; this gate is executing inside a subagent (a subagent is already model-pinned via its own frontmatter); OR an advisory for this LANE already printed this endeavor AND the active model is unchanged (advise at most once per (lane, active-model) pair per endeavor).
2. Resolve this skill's lane (own lane: frontmatter → the Skill→Lane table in .claude/skills/skill-builder/references/model-lanes.md → NO LANE) and the lane's Preferred Model. IF no lane resolves OR the preferred-model cell is empty → silent no-op (correctly absent, not a gap). IF this skill declares per-function lanes AND the invocation's resolved mode has its own row → that function's lane governs; otherwise the skill-level lane covers all modes.
3. Read ACTIVE_MODEL from the session system-context line "The exact model ID is …" (strip [1m]/[200k], lowercase — model-lanes.md § Active-Model Detection; never an env var or Bash probe). IF the Preferred Model is malformed or names a clearly superseded family → emit the one-line stale-mapping advisory and proceed; never advise from a stale mapping, never validate against a hardcoded list.
4. Compare. Match → silent no-op. Mismatch → print ONE advisory line and PROCEED: "Lane advisory: this skill declares the <lane> lane (preferred <preferred>); the active model is <active> — to align, run /model <preferred> and re-invoke; proceeding as-is." Naming the command is INFORMATIONAL (named-command advisory directive, 2026-06-11): NEVER an AskUserQuestion, never a blocking wait (No-Switch-Prompt directive, 2026-06-06). A skill can NEVER switch the session model and never asks the user to.
5. Primary-lane scope. This gate fires ONCE per invocation, for the resolved PRIMARY lane. Cross-lane mid-workflow steps never re-advise — they delegate via this skill's LANE-AGENT-EMBED Delegation Map when present (see .claude/skills/skill-builder/references/lane-delegation.md). Delegation is never a substitute for THIS gate: analytical primary work runs on the analytical main model — never a creative main session orchestrating analytical-pinned agents to dodge the lane.

1. Pick the mode. Editing/just wrote code → review (candidate set = the diff). Whole-tree request → sweep (candidate set = everything, report-only).
2. Ground before acting. Read references/cross-file-detection.md for the detection procedure, references/guards.md for the false-positive guards, and references/native-tool-map.md to prefer a real analyzer when present.
3. Run the native-tool gate first, then the ripgrep pipeline; reconcile every finding against the guards.
4. Tier every finding HIGH / MEDIUM / LOW. Display the plan first.
5. Auto-fix only HIGH, guard-cleared dead code, one atomic change at a time, through the safety cycle (baseline → remove → build → full tests → revert on any failure). Duplication and complexity are always human-decide.
6. For unbiased review at scale, spawn the deadcode-gardener agent (L2) so the evaluation runs in a clean context; for a full sweep, fan out one agent per top-level directory and aggregate.

Safety (non-negotiable)

• Default to report mode; deletion requires explicit --execute.
• Never auto-delete when any hard-forbidden guard fires (reflection, FFI, schema/ORM binding, public API, dynamic import/codegen, incomplete entry-point set, comment-only references, cross-boundary). See references/guards.md.
• Dynamic languages (Python/JS/Lua/Bash) have no compile-time net → extra confirmation, prefer report-only.

Enforcement coordination

These steps are no-ops unless /skill-builder code-eval enforce is wired on this host (the host-generated code-eval-* hooks in .claude/settings.local.json). They keep the shared markers (all under .claude/) consistent so the always-on hooks gate correctly. Skip silently when enforcement is not wired.

1. Loop guard — every review run. At the START of the run, touch .claude/.code-eval-active; at the END (success or failure), remove it. While it exists the enforce hooks skip, so the evaluator's own auto-fix edits never re-trigger the before/at-write gates.
2. Stamp on a clean pass. When review finishes with no outstanding MUST-FIX / HIGH findings, record the reviewed state and clear the debt:
   • { git diff HEAD; git status --porcelain; } | sha256sum | cut -d' ' -f1 > .claude/.code-eval-reviewed
   • rm -f .claude/.code-eval-pending .claude/.code-eval-advised This is what lets the commit gate (Phase 3) pass and clears the at-write list.
3. Before-write protocol. The Phase-1 block tells the caller (the main model) to consult the code-design-advisor, then touch .claude/.code-eval-advised and re-attempt the write. The advisor is read-only; the caller sets the marker.

Grounding

• references/cross-file-detection.md — detection procedure (read first)
• references/guards.md — the false-positive guards (read before flagging anything dead)
• references/mistake-taxonomy.md — what to look for
• references/native-tool-map.md — per-language tool preference
• references/gotchas.md — quick WRONG/CORRECT reminders