---
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.

{{PREAMBLE}}

## 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}}

{{CONTEXT_GATHERING}}

## 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_FOOTER}}

## 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)