CLI Audit Code

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.

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.

Context Budget Rule

Do not read a large source file end-to-end as the first step.

• For files over 300 lines or directory audits, start with inventory only: file list, line counts, symbol or function index, git churn, and focused risk greps.
• When evidence points at a line, read a bounded slice around it: about 75 lines before and after, 150 lines max by default. Use nl -ba path | sed -n 'START,ENDp', sed -n 'START,ENDp', or rtk read -n -m 150 path when RTK is available.
• Read a full file only when it is 300 lines or less, or when whole-file semantics are required. State that reason in the report.
• Reuse previously read slices and line references instead of re-reading the same file.
• Prefer RTK wrappers for noisy shell output when available: rtk git, rtk cargo, rtk grep, rtk find, and bounded rtk read. Do not treat generic rtk log output as authoritative for structured JSON logs unless a domain-specific filter verifies it.

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

Finding tier and confidence semantics are canonical in ../shared/triage.md (Tier 3/2/1 + GRADE + triangulation). Emit each finding with its tier and confidence so cli-cycle can aggregate without re-parsing.

Output Format

# 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

Dynamic Handoffs

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

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