Code Audit.instructions

---
applyTo: "**/*"
---

# Code Audit Workflow

When auditing this codebase for AI/LLM readiness, follow these phases:

## Audit Modes

- **Full audit** (default): evaluate all applicable rules
- **Quick audit** ("quick audit", "critical only"): evaluate only the critical-severity rules applicable to detected languages
- **Differential audit** ("audit changed files"): `git diff --name-only <ref>`, apply rules to changed files only
- **Dimension audit** ("audit tests"): evaluate only the specified dimension(s)

## Phase 1: Discovery
Scan for languages (*.py, *.ts, *.tsx, *.go, *.rs, *.java), dependency manifests, context files, and tooling configs. Determine if monorepo.
Also check for `.auditignore` (suppression) and `audit-report.json` (baseline for progress tracking).

## Phase 2: Rule Selection
Read #file:.audit-rules/index.md for the full rule inventory. Filter by detected languages. Load applicable dimension and language files from `.audit-rules/`.

Decision matrix:
- Always load: 01-file-size, 02-naming, 03-comments, 04-structure, 05-tests, 06-context-files, 07-safety, 10-tooling, 11-repo-hygiene
- Python → 09-lang-python.md + 08-types.md
- TypeScript → 09-lang-typescript.md + 08-types.md
- Go → 09-lang-go.md
- Rust → 09-lang-rust.md
- Java → 09-lang-java.md

## Phase 3: Evaluation
For each loaded rule file, evaluate every applicable rule using the method specified:
- static_analysis/filesystem_analysis/pattern_match: search files, run counts
- ast_analysis: read and analyze source structure
- llm_analysis: reason about comment quality, staleness, single responsibility. Include confidence (high/medium/low) for subjective findings.
- Include confidence for all heuristic evaluations (sampled complexity, dead code, tool fallbacks), not just llm_analysis.
- For 7.1.2 env_file_gitignored: check BOTH .gitignore patterns AND that no .env files are tracked in git.
- Also check `.audit-rules/custom/` for user-defined rules
- content_analysis: check documentation structure
- tool_output: run commands if available. Auto-SKIP if prerequisite rule failed (e.g., 10.1.1 → linter rules, 6.1.1 → context sub-rules)
- suppression: if `.auditignore` exists, suppress matching rules (SKIP suppressed, excluded from scoring)

Record: PASS/WARN/FAIL/SKIP with evidence (file paths, line numbers).

Exclude: node_modules/, vendor/, dist/, build/, target/, .git/, generated files.
For large codebases (100+ files), sample 15-20 files per language.

## Phase 4: Scoring
Read #file:.audit-rules/scoring.md. Calculate per-dimension and overall scores. WARN results receive 50% credit.
Check minimum viable thresholds (when applicable): 7.1.1, 4.2.1, 5.1.1 (>=60%), 6.1.1, 8.1.1 (>=80%, py/ts only), 10.1.1. Non-applicable must-pass rules → treat as PASS.

## Phase 5: Report
Output:
- Overall grade and score
- Minimum viable checks table
- Dimension scores table
- Issues grouped by severity with evidence and fix recommendations (at least 1 fix per issue)
- Passing rules list

## Phase 6: Fix Offer
Ask which issues to fix: all critical, all critical+high, pick specific, save as baseline (`audit-report.json`), or skip.
If baseline was loaded, append a Progress section (improvements, regressions, unchanged).
When fixing, reference templates in `.audit-rules/../fixes/`: context-file.md, linter-config.md, formatter-config.md, typescript-strict.md, gitignore.md, precommit-ci.md.
Apply fixes from templates, re-evaluate affected rules, report updated scores.