---
name: codebase-audit
description: Systematic deep audit and bulk remediation of an existing codebase — parallel subagent review, shared utility creation, fix application, and verification. Absorbed codebase-inspection (pygount-based LOC and language breakdown).
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [code-review, audit, security, bulk-fix, remediation, xss, accessibility, quality]
    related_skills: [requesting-code-review, subagent-driven-development, systematic-debugging]
---

# Codebase Audit & Bulk Remediation

Comprehensive error finding and fix application across a existing codebase (not a git diff).
Scales to 30+ files using parallel subagents for review, shared utilities for fixes, and
script-based verification.

**When to use:** User asks you to "check the code for errors", "find all the bugs",
"audit the project", "make all the fixes" — any request to systematically scan an
existing codebase (not just a diff or a single file).

**When NOT to use:** Pre-commit review of small changes (use `requesting-code-review`),
single-file analysis, debugging a specific bug (use `systematic-debugging`).

## Phase 1 — Survey

Before any review, understand the codebase structure:

```bash
# Get a file inventory
find /path/to/project -type f -name '*.js' -o -name '*.html' -o -name '*.css' | sort

# Quick size check per file
wc -l /path/to/project/**/*.js
```

### Codebase Size & Language Breakdown (pygount, absorbed from `codebase-inspection`)

For a structured overview of the codebase size, language composition, and code-vs-comment ratios, use `pygount`:

```bash
pip install --break-system-packages pygount 2>/dev/null || pip install pygount

pygount --format=summary \
  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,.eggs,*.egg-info,vendor,third_party" \
  .
```

**Always use `--folders-to-skip`** — without it, pygount crawls node_modules and can hang.

**Language-specific filtering:**
```bash
# Only count Python files
pygount --suffix=py --format=summary .
```

**Output columns:** Language, Files, Code lines, Comment lines, % of total.

**Pseudo-languages to expect:** `__empty__`, `__binary__`, `__generated__`, `__duplicate__`, `__unknown__`.

**Pitfall:** Markdown content is classified as comments (0 code lines). This is expected.

Identify the stack, key files, and group files into review batches of 5-8 files each.
Keep related files together (e.g., all shared/ files in one batch).

## Phase 2 — Parallel Subagent Review

Use `delegate_task(tasks=[...])` with up to max_concurrent_children subagents.
Each subagent gets a batch of files and a clear review mandate.

**Per-task structure:**
```python
{
    "goal": "Review these files for errors, bugs, security issues, and code quality problems. Report everything you find.",
    "context": "File paths, what each file does, what to prioritize",
    "toolsets": ["file"]
}
```

**Review categories to check every file for:**

- **🔴 Critical (will crash):** ReferenceError on undefined variables, TypeError on null/undefined access (.toDate() on null, .toUpperCase() on undefined), malformed API URLs, variable shadowing in closures
- **🟠 Security:** XSS via innerHTML with unsanitized user/Firestore data, inline onclick handlers with string interpolation (`onclick="fn('${data}')"`), client-side API keys, eval()-like patterns, subresource integrity (SRI) missing on CDN scripts, Content-Security-Policy absent
- **🟡 Logic bugs:** Infinite retries with no backoff, memory leaks (accumulating event listeners on re-render, timer nuking that clears ALL browser timers), duplicate field names in data models, missing null guards on optional fields
- **🟢 Accessibility:** Missing role="dialog"/aria-modal on modals, missing aria-live on dynamic content, missing aria-label on icon-only buttons, no focus trapping in modals, no skip-to-content link
- **⚪ Quality:** Dead code (empty files, unreachable branches), excessive console.log, redundant duplicate code, hardcoded magic numbers

## Phase 3 — Prioritize and Plan Fixes

Aggregate all findings from subagents, group by severity, and plan the fix order:

1. **Critical crashes** first — these break the app at runtime
2. **Security vulnerabilities** — XSS, exposed keys, CSP/SRI
3. **Logic bugs** — retries, memory leaks, data integrity
4. **Accessibility** — screen reader support
5. **Code quality** — cleanup

## Phase 4 — Create Shared Utilities

Before fixing individual files, create any shared helpers the fixes need:

```javascript
// shared/sanitize.js — XSS prevention
export function escapeHtml(value) {
    if (value == null) return '';
    const str = String(value);
    const div = document.createElement('div');
    div.appendChild(document.createTextNode(str));
    return div.innerHTML;
}
```

Create this FIRST so all fix subagents can import it.

## Phase 5 — Apply Fixes in Parallel

Use `delegate_task(tasks=[...])` again, this time for fixes. Group related fixes:

**Batch structure (common groupings):**
- **Bug-fix batch:** 1 subagent per large file (dashboard.js, repair-orders.js)
- **XSS batch:** 1 subagent to add escapeHtml imports + wrap all interpolations across 5-8 files
- **HTML/a11y batch:** index.html and all other HTML pages
- **Config batch:** firebase.json, etc.

**Fix patterns to apply:**
```javascript
// Before (XSS via innerHTML):
element.innerHTML = `<div>${userData}</div>`;

// After:
element.innerHTML = `<div>${escapeHtml(userData)}</div>`;

// Before (null crash):
writeupTime: doc.data().writeupTime.toDate()

// After (optional chaining):
writeupTime: doc.data().writeupTime?.toDate?.() ?? new Date()

// Before (infinite retry):
setTimeout(() => loadData(), 3000);

// After (bounded retry):
let retryCount = 0;
function retry(fn, max = 3, delay = 3000) {
    retryCount++;
    if (retryCount > max) return;
    setTimeout(fn, delay * Math.pow(2, retryCount - 1));
}
```

**Per-fix-subagent instructions must be SPECIFIC** — list exact line ranges or
search patterns, exact old_string → new_string, and how to find them
(e.g., "search for `onclick=\"...\${...}` patterns in repair-orders.js").

## Phase 6 — Verification

After all fixes, run a grep-based verification script to confirm each fix was applied:

```python
from hermes_tools import terminal

checks = [
    ('file.js', 'pattern_to_confirm'),
    ('file.js', 'escapeHtml'),  # check XSS fix applied
]

for file, pat in checks:
    r = terminal(f"grep -c '{pat}' '{path}' 2>/dev/null || echo '0'")
    count = r['output'].strip().split('\n')[0]
    ok = count != '0'
    print(f"{'✅' if ok else '❌'} {file}: '{pat}' -> {count}")
```

## Pitfalls

- **Subagents exceed tool iteration limits** — big files (3000+ lines) may hit 50-iteration cap. Split fixes across multiple subagents or fix smaller batches at a time.
- **Patch tool finds multiple matches** — when a pattern appears in two similar functions (e.g., both `getPriorityAnalysis` and `handleAiWrite`), use `replace_all=True` or add more context lines to disambiguate.
- **Re-read warnings** — subagents that modify files you previously read will trigger "file was last read with partial view" warnings. Re-read the file before further patches.
- **XSS is pervasive** — in a ~30 file codebase, expect 80-120+ interpolation points. Don't try to fix them all in one subagent task; batch by file group.
- **Timer nuking** is a common anti-pattern in prototyped apps — watch for `for (let i = 0; i < highestTimeoutId; i++) clearTimeout(i)` patterns.
- **delegate_task max_concurrent_children** defaults to 3. If you need more parallelism, mention it to the user.
- **Don't fix what you can't verify** — API keys marked `***` can't be fixed to real values; mark them as TODO. Empty cloud functions stubs with no exports are intentional blanks.