---
name: code-quality-audit
description: Audit code for smells, error-handling gaps, and maintainability issues with actionable fixes. Use for a general code-quality pass not tied to project rules. To audit against the project's golden-principles.yaml use /quality-audit instead.
user-invocable: true
---

# Code Quality Audit

## Core Rule

Surface issues that affect maintainability and correctness, not stylistic preferences. Recommend fixes only with concrete reproduction steps; never apply edits in a report-only request.

## Kit Context

Before starting this skill, ensure you have completed session boot:
1. Read `CODEBASE_MAP.md` for project understanding
2. Read `CLAUDE.project.md` if it exists for project-specific rules
3. Read `tasks/lessons/_index.md` for accumulated corrections (Top Rules + index)

If any of these haven't been read in this session, read them now before proceeding.

## When to Use

Invoke with `/code-quality-audit` when:

- Reviewing a codebase for code smells before a refactoring sprint
- Onboarding to a new project and assessing code health
- Preparing for a code review or due diligence assessment
- After rapid development to identify accumulated technical debt

## Default Behavior

When the user asks to audit, scan, review, or "give me a report" for code quality, produce the full code-quality-audit report automatically using the Process and Output Format sections below. Do not require the user to specify fields.

Only modify files when the user explicitly requests implement / fix / apply / refactor. By default, this skill is **report-only**.

## Scope Rules

- Analyze ONLY the files and directories relevant to this skill's purpose
- Do not refactor, fix, or modify code — this is a read-only analysis unless explicitly stated otherwise
- Log unrelated issues found during analysis under `tasks/todo.md > ## Not Now`
- State every assumption explicitly before acting on it
- If the user specified a scope (files, directories, modules), respect it strictly

## Context Gathering

Before analysis, map the project:
1. Read project config (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.)
2. Identify the tech stack, frameworks, and key dependencies
3. Map source directories — skip `node_modules`, `vendor`, `build`, `.next`, `dist`, `__pycache__`
4. Check for existing configurations relevant to this analysis (linters, formatters, CI configs)
5. If the user specified a scope, narrow to those files/directories only

## Process

### Phase 1: Inventory (first-pass leads)

This pass produces **candidates**, not findings. Treat counts as leads for deeper inspection in later phases. Do not report Phase 1 raw output as the final result.

Determine audit scope:

1. If the user specifies files/directories, audit those
2. Otherwise, identify key source directories by reading project structure
3. Skip generated code, vendor directories, lock files, and build output

### Phase 2: Code Smells Analysis

Scan for these categories of code smells:

**Complexity Smells**
- Functions/methods exceeding 50 lines
- Deeply nested conditionals (3+ levels)
- Cyclomatic complexity > 10 per function
- God classes/modules with too many responsibilities
- Long parameter lists (5+ parameters)

**Duplication Smells**
- Repeated code blocks (3+ occurrences of similar logic)
- Copy-paste patterns with minor variations
- Parallel inheritance hierarchies
- Identical conditional structures across files

**Coupling Smells**
- Feature envy (method uses another class's data more than its own)
- Inappropriate intimacy (classes accessing each other's internals)
- Message chains (a.b.c.d.method())
- Circular dependencies between modules

**Naming Smells**
- Inconsistent naming conventions within the same codebase
- Overly abbreviated or cryptic names
- Boolean parameters without named arguments
- Generic names (data, info, manager, handler) without context

### Phase 3: Error Handling Analysis

Check for error handling issues:

- **Swallowed errors**: empty catch blocks, catch-and-log-only without re-throw
- **Over-catching**: catching base Exception/Error when specific types are appropriate
- **Missing error handling**: async operations without try/catch, unchecked return values
- **Inconsistent patterns**: mix of exceptions, error codes, Result types without clear convention
- **Error information loss**: re-throwing without preserving original stack trace
- **Missing cleanup**: no finally/defer/cleanup for resources in error paths
- **User-facing errors**: raw stack traces or internal errors exposed to users

### Phase 4: Maintainability Assessment

Evaluate:

- **Readability**: Can a new developer understand the code without external context?
- **Testability**: Can units be tested in isolation? Are dependencies injectable?
- **Changeability**: How many files need to change for a typical feature addition?
- **Consistency**: Are patterns applied uniformly across the codebase?

## Output Format

```markdown
# Code Quality Audit Report

## Executive Summary
[1-2 paragraphs: overall quality assessment, critical findings count]

## Critical Issues (Must Fix)
| # | Category | Location | Issue | Suggested Fix |
|---|----------|----------|-------|---------------|
| 1 | smell    | file:line | ...   | ...           |

## Major Issues (Should Fix)
| # | Category | Location | Issue | Suggested Fix |
|---|----------|----------|-------|---------------|

## Minor Issues (Consider)
| # | Category | Location | Issue | Suggested Fix |
|---|----------|----------|-------|---------------|

## Metrics
- Files analyzed: N
- Code smells found: N (critical/major/minor)
- Error handling gaps: N
- Estimated tech debt: low/medium/high

## Positive Patterns
[List well-implemented patterns worth preserving]
```

## Report Guidelines

- Use tables for structured findings — they're scannable and diffable
- Include file paths with line numbers (`file.ts:42`) for every finding
- Separate findings by severity: Critical > Major > Minor
- End with actionable recommendations, not just observations
- If no issues found in a category, state it explicitly — don't omit the section

## Notes

- This audit focuses on code-level quality, not architecture (see `/architecture-review`)
- Security issues should be flagged but detailed security review is separate (use security-reviewer agent)
- Adapt smell thresholds to the project's language conventions (e.g., functional languages may have longer functions)