ai-code-tells

AI-Code Tells Review

A focused, read-only review that catches the five consistent signatures of AI code that nobody read before accepting it. It does not fix anything by default — it reports findings so a human keeps the mental model. Apply fixes only when the user asks.

The five tells below are the complete rule set — the skill needs no external configuration. If your user-level or project CLAUDE.md defines equivalent always-on code-quality guardrails, this skill acts as their on-demand review pass; honor any project-level tightening in the repo's own CLAUDE.md (e.g. hard gates).

When to Activate

• The user invokes /ai-code-tells or asks to "check for AI tells / AI smells".
• After generating a non-trivial chunk of code, before presenting it as done.
• Before opening a PR, as a self-review pass.

Scope — what to review

Resolve the target in this order, stop at the first that applies:

1. An explicit path, file list, or PR number the user named.
2. Staged changes: git diff --cached. If empty →
3. Working-tree changes: git diff. If empty →
4. The current branch vs its merge-base with the default branch: git diff $(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main)...HEAD.

Review only the changed lines and enough surrounding context to judge them. Do not audit the whole repo. If nothing is in scope, say so and stop.

The five tells

For each, scan the diff and record findings. A finding is file:line — <tell> — why it's a tell — concrete fix.

1. Narrating comments. Comments that restate what the code literally does (// increment counter, // loop over the list and process each item, // return the result). The fix: delete it, or replace it with the why (a decision, constraint, or gotcha) if one exists. A method whose every line has a play-by-play comment is the strongest signal.

2. Generic, domain-blind names. Identifiers like data, result, item, value, obj, temp, process(), handle(), doStuff(), Manager, Helper, Util where a domain word exists. The fix: rename to what it is in the problem domain. Flag only where a more meaningful name is genuinely available — loop indices and trivially-scoped temporaries are fine.