Guard AI-generated code against systematic quality failures

This skill reviews generated or changed code before it ships, applying a guard pass after the first implementation pass and re-running it after every later edit in the same session rather than reverting to unguarded output once the skill has loaded. It exists because LLM-generated code has measurable, systematic failure modes that generic "follow clean code" instructions miss: code duplication grew 8x in tracked codebases between 2021 and 2024 (GitClear), package hallucination averages 19.6% across 16 models (Spracklen et al., USENIX Security '25), LLMs commonly wrap risky operations in broad catch-all handlers that swallow errors (Karpathy), agents declare success despite failing tests by returning hardcoded fixture values (Fowler), and function size grew from 142 to 267 lines with cyclomatic complexity from 4.2 to 8.1 in AI-assisted commits (GitClear). Classic Clean Code/SOLID/DRY-KISS-YAGNI principles are still the foundation, but this skill adds the AI-specific layer most rule packs miss.

It runs in three modes: guard-pass (recommended, checking a diff or target files against its imperatives after code is written), live mode (applying the same imperatives while writing, then a self-check), and review mode (walking a structured checklist to produce findings without editing unless asked). Rule detail lives in seven reference files - naming/functions, comments/formatting, SOLID, DRY/KISS/YAGNI, a 14-item AI-failure-modes file flagged as the highest-leverage read for an AI agent, the review checklist, and a source bibliography.

Twenty-four always-applied imperatives, grouped. Functions and names: names must reveal intent (banning bare data/result/temp/helper/manager without a qualifier); functions stay at 20 lines or fewer, one abstraction level, one thing; four arguments is the hard ceiling, with a request object past that and no boolean flag arguments; and a function either returns a value or has a side effect, never both (command-query separation). Comments and structure: comments explain why, never what, and commented-out code gets deleted since version control exists; new code matches the file's existing style rather than introducing a second pattern. SOLID: one stakeholder group per module (SRP); new variants extend via registry/strategy/polymorphism rather than another branch in an existing function (OCP); no subclass override signals "unsupported" or weakens its parent's contract (LSP); and abstractions live in the consuming package, not next to the concrete class (DIP). DRY/KISS/YAGNI: delete duplicated knowledge, not duplicated-looking text; re-inline a wrong abstraction that's accumulated per-caller branches before re-abstracting (Sandi Metz); keep cyclomatic complexity at 10 or below and nesting at 5 or below; and never add a speculative parameter, flag, or interface with no present-day caller.

The AI-specific guardrails section covers: never swallowing errors in a broad catch-all (catch only what you can recover from, or let it propagate); guarding trust boundaries (external input, deserialized data) while trusting the contract inside them; verifying every import and external call actually exists in the installed version rather than generating from what an API "should" look like; never returning hardcoded success or mock fixtures from production code, and never weakening a test to make it pass; re-deriving from spec instead of copying and modifying a similar function, since off-by-one bugs enter through copy-from-similar; enumerating boundary cases (range, off-by-one, null/empty, unicode) before writing them; stripping dead code and unused exports before delivery; reading the target file, a neighbor, and any project rules file before writing in an unfamiliar repo; and never adding a new dependency for what a few lines of local code already cover.

Four items form a floor that never gets cut for simplicity even while stripping speculation or dead code: validation at every trust boundary, error handling that prevents data loss, security measures (authorization, escaping, parameterized queries, secrets), and behavior the user explicitly requested. Refactoring must preserve observable behavior exactly - a spotted bug gets flagged separately and asked about, never bundled into the same change. The self-check before delivery walks all 24 imperatives against the diff, checking function size/params/complexity, comment quality, error-handler specificity, whether new abstractions have a second concrete user today, and whether a refactor changed any observable behavior. After the pass it reports each actual fix made (never an invented quality score) and closes with a one-line summary like clean-code-guard: 3 fixed, 1 flagged for author.

Use it reactively after an agent writes, edits, or refactors production code, or proactively in live mode before a risky edit. It requires no MCP server, network access, API key, or bundled executable - it's a portable instruction skill usable anywhere SKILL.md plus its reference files can be read. It stays silent for conceptual, CI, git-workflow, prose, data-analysis, and test-running tasks, does not run linters or static analysis itself, does not enforce formatter preferences, and does not replace tests - clean code passes tests, but clean code without tests is still a defect.

Input is generated or changed production code (a diff or target files) plus the project's own conventions (CLAUDE.md/AGENTS.md, README conventions) which win on conflict. Output is either corrected code with a fix-count summary (guard-pass/live mode) or a structured findings report (review mode).

It defers to the project's own linters, formatters, type checkers, and test runners for mechanical verification, reserving itself for the judgment layer around code quality, and pulls its rule detail from seven reference files covering naming, comments, SOLID, DRY/KISS/YAGNI, AI-specific failure modes, the review checklist, and a source bibliography.

Developers and agents shipping AI-generated or AI-assisted code who need the AI-specific failure modes (hallucinated imports, hardcoded success returns, copy-from-similar bugs) caught alongside classic clean-code violations, with refactors verified to preserve behavior exactly.