code-audit

Code Audit: Noetic Investigation Skill

Investigate code quality. Produce structured remediation plans.

This skill is purely noetic — it discovers, triages, and plans. It does NOT make changes. The output (findings, goals, decisions) feeds directly into the Empirica workflow for any praxic agent to pick up and execute.

---

How to Run

/code-audit                              # Audit entire project
/code-audit --target src/handlers/       # Audit specific directory
/code-audit --target src/auth.py         # Audit specific file
/code-audit --focus duplication          # Focus on one dimension

---

Phase 1: Scope

Determine what to audit. If the user specified a target, use it. Otherwise, audit the current project root.

# Determine scope
TARGET="${1:-.}"  # Default to current directory

# Quick size assessment
find "$TARGET" -name "*.py" | wc -l          # File count
find "$TARGET" -name "*.py" -exec wc -l {} + | tail -1  # Total LOC

Log the audit scope:

empirica finding-log --finding "Audit scope: $TARGET — N files, N LOC" --impact 0.1

---

Phase 2: Automated Tool Passes

Run external tools and parse results into findings. Each tool covers a different dimension. Skip any tool that isn't installed — the audit still works without it.

2a. Linting & Style (ruff)

ruff check "$TARGET" --statistics --output-format json 2>/dev/null

Parse results:

• Group by rule category (import order, unused imports, complexity, etc.)
• Log aggregates as findings, not individual violations
• Impact scoring: unused imports = 0.2, complexity violations = 0.5, security = 0.8

# Example: aggregate finding
empirica finding-log --finding "ruff: 23 unused imports across 8 files (F401)" --impact 0.2
empirica finding-log --finding "ruff: 5 functions exceed complexity limit (C901)" --impact 0.5

2b. Dead Code (vulture)

vulture "$TARGET" --min-confidence 80

Parse results:

• Filter out false positives (dynamically called functions, CLI entry points)
• Log confirmed dead code as findings
• Log uncertain cases as unknowns