code-audit

name: code-audit description: "Use when the user says '/code-audit', 'audit this code', 'check code quality', 'find duplication', 'find dead code', 'code cleanup', 'technical debt audit', 'code review module', or wants a structured noetic investigation of code quality. This skill runs external analysis tools and structured manual review, producing Empirica artifacts (findings, goals, decisions) that any praxic agent can execute." version: 1.0.0

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

empirica finding-log --finding "vulture: 12 unused functions detected (80%+ confidence)" --impact 0.4
empirica unknown-log --unknown "vulture flagged handle_legacy_sync() — verify if called dynamically"

2c. Complexity Metrics (radon)

radon cc "$TARGET" -s -a --min C    # Only show functions rated C or worse
radon mi "$TARGET" -s --min B       # Maintainability index

Parse results:

• Functions rated C (11-20) → finding with impact 0.4
• Functions rated D (21-30) → finding with impact 0.6
• Functions rated F (31+) → finding with impact 0.8
• Log the worst offenders by name and file

empirica finding-log --finding "radon: process_vectors() in workflow_commands.py has CC=27 (D)" --impact 0.6

2d. Type Errors (pyright)

pyright "$TARGET" --outputjson 2>/dev/null

Parse results:

• Count errors by category (missing types, incompatible types, possibly unbound)
• Log aggregates, not individual errors

empirica finding-log --finding "pyright: 45 type errors — 20 missing annotations, 15 incompatible, 10 unbound" --impact 0.3

Phase 3: Structural Review (Manual)

These dimensions require AI judgment — tools can't catch them.

3a. File Size Analysis

find "$TARGET" -name "*.py" -exec wc -l {} + | sort -rn | head -20

Thresholds:

• >2000 LOC → finding with impact 0.5 ("needs splitting")
• >1000 LOC → finding with impact 0.3 ("consider splitting")
• >500 LOC → note only

empirica finding-log --finding "project_commands.py: 4214 LOC — contains 17 unrelated handlers, needs splitting" --impact 0.6

3b. Duplication Detection

Search for functions defined in multiple places:

# Find duplicated function definitions
grep -rn "^def " "$TARGET" | awk -F: '{print $NF}' | sort | uniq -c | sort -rn | head -20

# Find copy-pasted patterns (same function name in multiple files)
grep -rn "def get_instance_id\|def find_project_root\|def resolve_project" "$TARGET"

For each duplicate: Read both copies. Assess whether they're identical, similar, or intentionally different. Log accordingly:

# Identical copies
empirica finding-log --finding "get_instance_id() duplicated identically in 6 files" --impact 0.6

# Intentionally different (record WHY)
empirica decision-log --choice "Keep separate find_project_root() in hooks" \
  --rationale "Hooks must be standalone — can't import from package" \
  --reversibility exploratory

3c. Module Boundary Assessment

Read the import graph. Check for:

• Circular imports — A imports B, B imports A
• Layer violations — CLI importing from data, data importing from core
• God modules — single file that everything imports

# Check for late imports (circular dependency workaround)
grep -rn "import " "$TARGET" | grep "def \|if " | head -20

3d. Naming & Convention Consistency

Spot check:

• Mixed naming styles (snake_case vs camelCase)
• Inconsistent patterns (some files use handle_X_command, others use X_handler)
• Magic strings/numbers without constants

3e. Error Handling

# Find bare exception handlers
grep -rn "except Exception" "$TARGET" | grep "pass"
grep -rn "except:" "$TARGET"

empirica finding-log --finding "12 bare 'except Exception: pass' handlers — errors silently swallowed" --impact 0.5

Phase 4: Triage

Review all findings. Assign categories and prioritize.

Categories:

Impact scoring guide:

Phase 5: Create Remediation Goals

Group related findings into actionable goals. Each goal should be independently executable by a praxic agent.

Goal template:

empirica goals-create --objective "Split project_commands.py into focused modules (artifact_log, workspace, ecosystem)"

Good goals have:

• Clear scope — which files, what changes
• Success criteria — how to verify it's done
• Linked findings — why this goal exists (reference finding IDs)
• Dependencies — what must happen first

Goal sizing:

• Each goal = 1 transaction of praxic work
• If a goal would take 3+ transactions, split it further
• If two goals always need to happen together, merge them

Phase 6: Record Decisions

Not every finding needs a fix. Some are acceptable trade-offs. Record these explicitly:

# Accept a trade-off
empirica decision-log --choice "Accept hook utility duplication" \
  --rationale "Hooks must be standalone — extracting to shared module is the fix, not eliminating all copies" \
  --reversibility exploratory

# Defer work
empirica decision-log --choice "Defer type hint completion to separate effort" \
  --rationale "Functional correctness over type coverage for now" \
  --reversibility easily_reversible

Why this matters: Enterprise auditors want to see that decisions were conscious, not accidental. A documented "we chose to keep this" is better than unexplained duplication.

Phase 7: Summarize

Present the audit results to the user:

1. Scope — what was audited
2. Tool results — aggregate numbers from ruff, vulture, radon, pyright
3. Top findings — sorted by impact
4. Goals created — the remediation plan
5. Decisions recorded — what was accepted/deferred and why
6. Unknowns remaining — what needs further investigation

# Show the full picture
empirica goals-list

Output Contract

After /code-audit completes, the following artifacts exist in the Empirica DB:

Any agent can then:

empirica goals-list                    # See the work
empirica preflight-submit - << 'EOF'   # Start a transaction
# ... pick up a goal and execute it

Re-Running

The skill is idempotent. Running /code-audit again after remediation shows:

• Which findings are resolved (goals completed)
• Which persist (goals still open)
• New findings from changes (regression detection)

Compare audit runs over time to track code quality trajectory.