# Code Quality Guide

> Use when auditing existing code for quality WITHOUT changing it: a read-only pass that finds smells, grades them by severity, and routes each to its owner. Triggers on robustness or hardening, duplication, dead code, over-abstraction, complexity, magic numbers, inconsistent implementations, barrel exports, redundant comments, shared-extraction candidates, TODO/FIXME inventory, or a code-smell audit, even when the user doesn't say 'audit' or 'code quality'.

- Skill: `xonovex/code-quality-guide` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add xonovex/code-quality-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xonovex/code-quality-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: xonovex (https://skillmd.com/u/xonovex)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xonovex/code-quality-guide

---


# Code-Quality Audit

A read-only pass over existing code: find smells, grade them by severity, report, and route each smell to the one skill that owns its definition and fix. It changes nothing.

## Essentials

- **Read the project's own standards first**: `AGENTS.md` / `POLICY.md` / linked guidelines and the linter config decide what counts as a violation, not generic best-practice
- **Robustness is this skill's own dimension**: type safety, validation, error handling, logging at boundaries, complexity, see [references/robustness.md](references/robustness.md)
- **Route every other smell to its owner**: the catalog maps each smell to a detector signal and the skill that owns it, see [references/smell-catalog.md](references/smell-catalog.md)
- **Keep cleanup inventories read-only**: preserve functional comments and rationale; detect prose debt and other cleanup candidates, see [references/comment-inventory.md](references/comment-inventory.md) and [references/cleanup-inventories.md](references/cleanup-inventories.md)

## Gotchas

- This skill is a read-only **detector and grader**. It names a smell and routes to the owner (**oop-guide** for OO-design smells, **connascence-guide** for coupling smells); it does not redefine or fix them.
- "Dead code" detection misses code reached via dynamic dispatch, reflection, or external entry points: verify before flagging for deletion.
- A single-implementation interface is not automatically over-engineering. It may exist for testability or a planned variant.
- Preserve comments that explain a non-obvious why, invariant, workaround, or caveat; flag restatements and plan or provenance narration.
- The "application / class / method-level" smell grouping is an informal label, not a citable taxonomy: the smell catalog groups by design-problem family instead.
- Log at boundaries and on error paths, validate at trust boundaries: "everywhere" is noise and wasted work, not robustness.

## Progressive Disclosure

- Read [references/robustness.md](references/robustness.md) - Load when auditing robustness: type safety, validation, error handling, logging, complexity
- Read [references/smell-catalog.md](references/smell-catalog.md) - Load when mapping a smell to its detector signal and owning skill (oop-guide / connascence-guide / here)
- Read [references/comment-inventory.md](references/comment-inventory.md) - Load when inventorying redundant, stale, narrative, commented-out, directive-like, or ambiguous comments and docstrings
- Read [references/cleanup-inventories.md](references/cleanup-inventories.md) - Load when inventorying barrels, duplicated shared candidates, or TODO/FIXME clusters