Cli Audit Code

---
name: cli-audit-code
metadata:
  author: Destynova2
description: "Audit code quality with weighted scoring across 12 dimensions (naming, complexity, module design, DRY, errors, security, tests, architecture). Detects named anti-patterns (Fowler/Mantyla taxonomy). Use when reviewing code quality, auditing clean code compliance, checking for code smells, or saying 'audit code', 'code quality', 'code review', 'tech debt'. Invoke with an optional file or directory path."
argument-hint: "[file-or-directory]"
context: fork
agent: general-purpose
---

> **Optimization:** This skill uses on-demand loading. Heavy content lives in `references/` and is loaded only when needed.

> **Language rule:** Skill instructions are written in English. When generating user-facing output, detect the project's primary language (from README, comments, docs, commit messages) and produce the report in that language. If the project is bilingual, ask the user which language to use before proceeding.

# Audit Code — Code Quality Index (CQI)

> "Complexity is the single greatest enemy of reliability." — John Ousterhout

## Core Principles

1. **Evidence-based** — every finding needs a `file:line` reference. No vague "the code could be better"
2. **Proportional** — a 200-line function matters more than a missing doc comment. Scale to project type
3. **Language-aware** — detect the project language and apply its idiomatic patterns, not Java/C# defaults
4. **Named anti-patterns** — use Fowler/Mantyla taxonomy names (Feature Envy, Shotgun Surgery) in findings
5. **Positive reinforcement** — always highlight good practices found, not just violations
6. **Gotchas** — read `../../gotchas.md` before producing output to avoid known mistakes

## Input

`$ARGUMENTS` is the target to audit (file path, directory, or empty for whole `src/`).

- If a specific file: audit that file deeply
- If a directory: audit all source files in it
- If empty: audit `src/` broadly (sample 15-20 key files)

## 12-Dimension Framework

Score each dimension **0.0-1.0**, then compute a weighted CQI. Read `references/categories.md` for detailed check lists per category.

| # | Category | Weight | Key question |
|---|----------|--------|-------------|
| C1 | Naming & Readability | 8% | Do names reveal intent? No magic numbers? |
| C2 | Functions & Cognitive Complexity | 12% | < 30 lines? Cognitive complexity < 15? |
| C3 | Module Design (deep vs shallow) | 10% | Deep modules? No pass-through layers? |
| C4 | DRY & Change Amplification | 8% | One change = one file? No copy-paste? |
| C5 | Error Handling & Robustness | 10% | Errors propagated? No swallowed errors? |
| C6 | Type Safety & Language Idioms | 8% | Type system leveraged? Idiomatic patterns? |
| C7 | Comments & Public API Docs | 5% | Public API documented? No redundant comments? |
| C8 | Test Quality | 12% | Error paths tested? No flaky tests? |
| C9 | Security & Input Validation | 10% | Inputs validated at boundaries? No hardcoded secrets? |
| C10 | Immutability & State Management | 7% | Minimal mutable state? No global mutables? |
| C11 | Cognitive Load & Control Flow | 5% | < 3 nesting levels? No negative conditionals? |
| C12 | Dependencies & Architecture | 5% | No circular deps? DIP respected? |

## Workflow

### Step 1 — Discover and sample

Glob source files. For broad audit, prioritize: entry points, public API modules, most-changed files (git log), largest files.

### Step 2 — Detect language and context

Identify project language, framework, and type (library, CLI, service, script). This determines which idiom checks apply and what scoring standards are proportional.

### Step 3 — Score all 12 dimensions

Read `references/categories.md` for detailed checks. For each category: collect evidence, assign score 0.0-1.0, note specific `file:line` findings.

### Step 4 — Compute CQI and detect anti-patterns

Read `references/scoring.md` for the CQI formula, severity classification, named anti-patterns table, tech debt estimation, and comparative benchmarks.

```
CQI = Σ(wᵢ × sᵢ) / Σ(wᵢ) × 10
```

### Step 5 — Generate report

## Output Format

```markdown
# Code Quality Audit — {project-name}

**Target**: [file/directory] | **Language**: [detected] | **Date**: [date]
**CQI Score**: X.X/10 — {verdict} | **Tech Debt**: ~Xh ({SQALE grade})

## Scores by Category

| # | Category | Weight | Score | Weighted | Findings |
|---|----------|--------|-------|----------|----------|
| C1-C12 rows with 0.0-1.0 scores... |
| | **CQI** | **100%** | | **X.X/10** | |

## Anti-Patterns Detected
| Pattern | Severity | File:Line | Recommendation |

## Critical Violations (must fix)
### [Category]: [violation title]
- **File**: `path/to/file:123`
- **What**: [description]
- **Why**: [named principle/smell it violates]
- **Fix**: [concrete suggestion]
- **Disproof**: [observation that would invalidate this finding — e.g., "this isn't dead code IF dynamic dispatch is used here"]

## Flags (should fix)
[same format]

## Good Practices Found
[positive reinforcement]

## Recommended Next Steps
1. [highest-impact fix first]
2. [second]
3. [third]
```

## What this skill does NOT do

- **Does not fix code** — it reports. Use the findings to guide refactoring
- **Does not replace linters** — it complements them with semantic analysis a linter can't do
- **Does not check test coverage numbers** — it checks test quality. Use `cli-audit-test` for test strategy
- **Does not audit documentation quality** — use `cli-audit-doc` for that

## Integration with other cli-* skills

| Skill | Relationship |
|-------|-------------|
| `cli-audit-doc` | Scores doc quality. cli-audit-code scores **code quality** |
| `cli-audit-test` | Scores test strategy. cli-audit-code checks **test code quality** (C8) |
| `cli-forge-lld` | Validates implementation matches the LLD design |
| `cli-cycle` | Calls cli-audit-code as part of full project review |

## Dynamic Handoffs

After your analysis, recommend these skills if conditions are met:

| Condition detected | Recommend | Why |
|-------------------|-----------|-----|
| God class/module (C3 > 500 lines, many responsibilities) | `/cli-audit-tangle` | Topology analysis reveals optimal split points |
| Hardcoded secrets or `.env` tracked in git (C9) | `/cli-git-conventional --audit-markers` | Check git history for leaked secrets |
| Shell scripts in the project with quality issues | `/cli-audit-shell` | Deep bash-specific audit beyond C6 idioms |
| Missing or stale documentation (C7 low) | `/cli-forge-doc` | Generate/update project docs |
| Test quality issues (C8 low) | `/cli-audit-test` | Full test strategy audit |
| CI/CD config present but not audited | `/cli-forge-pipeline` | Pipeline optimization |

**Rule:** Recommend, don't auto-execute. Phrase as: "Consider running `/cli-audit-tangle` — 3 god modules detected that need topology analysis."

## Reference Sources

- Ousterhout — *A Philosophy of Software Design* | Martin — *Clean Code* | Fowler — *Refactoring* | Tornhill — *Software Design X-Rays* | Feathers — *Working Effectively with Legacy Code*
- SonarQube Quality Model | SonarSource Cognitive Complexity | SQALE Method | CodeScene Code Health | Clippy lint categories
- CodeAesthetic | ThePrimeagen | ArjanCodes | Software Engineering Radio | Tech Lead Journal