audit

# Audit

## Purpose

Audit is the comprehensive codebase analysis orchestrator. It systematically examines a codebase across four dimensions -- security, code quality, performance, and accessibility -- and produces a prioritized report of findings with remediation recommendations. Think of it as a thorough health checkup for your code.

Audit is read-only by default. It analyzes and reports but does not change code unless the user explicitly asks it to fix findings. This makes it safe to run at any time without risk of unintended changes.

## Workflow

### Phase 1: Scope & Inventory
1. **Parse audit parameters** -- Determine what to audit (full or specific dimensions) and any focus areas.
2. **Invoke `scout`** -- Build a comprehensive inventory of the codebase:
   - File count and types
   - Directory structure
   - Dependency list and versions
   - Configuration files
   - Test coverage status
   - CI/CD configuration
3. **Establish baselines** -- Record current metrics:
   - Test count and pass rate
   - Lint error count
   - Bundle size (if applicable)
   - Dependency count and age

### Phase 2: Security Audit
4. **Dependency vulnerability scan** -- Check all dependencies for known vulnerabilities:
   - Outdated packages with security patches available
   - Packages with known CVEs
   - Abandoned or unmaintained dependencies
5. **Secret detection** -- Scan for accidentally committed secrets:
   - API keys, tokens, passwords in source code
   - Hardcoded credentials in configuration
   - Secrets in git history (if accessible)
   - Proper .gitignore coverage for sensitive files
6. **Input validation analysis** -- Check all user input handling:
   - SQL injection vectors (raw queries, string concatenation)
   - XSS vectors (unescaped output, unsafe innerHTML usage)
   - Command injection (exec, spawn with user input)
   - Path traversal (file operations with user input)
7. **Authentication & authorization review** -- Examine auth implementation:
   - Session management (secure cookies, expiration, rotation)
   - Token handling (JWT validation, refresh flow, storage)
   - Route protection (middleware coverage, missing auth checks)
   - CORS configuration
   - Rate limiting
8. **Data handling review** -- Check sensitive data practices:
   - PII exposure in logs
   - Encryption at rest and in transit
   - Data sanitization before storage
   - Proper error messages (no stack traces to users)

### Phase 3: Code Quality Audit
9. **Architecture analysis** -- Evaluate structural health:
   - Separation of concerns adherence
   - Single responsibility violations
   - Circular dependencies
   - Module coupling analysis (via `mermaid` dependency graph)
   - Dead code detection
10. **Code patterns analysis** -- Check for antipatterns:
    - God objects or functions (> 200 lines)
    - Deep nesting (> 4 levels)
    - Callback hell or promise chains
    - Magic numbers and strings
    - Copy-paste code (DRY violations)
    - Inconsistent naming conventions
    - TODO/FIXME/HACK comment inventory
11. **Error handling analysis** -- Examine error management:
    - Uncaught promise rejections
    - Empty catch blocks
    - Generic error messages
    - Missing error boundaries (React)
    - Insufficient logging
12. **Test quality analysis** -- Evaluate the test suite:
    - Coverage percentage and gaps
    - Test quality (assertions per test, edge cases)
    - Flaky test indicators
    - Missing test categories (unit, integration, e2e)
    - Test organization and naming

### Phase 4: Performance Audit
13. **Bundle analysis** (frontend) -- Evaluate client-side performance:
    - Bundle size and composition
    - Tree-shaking effectiveness
    - Code splitting coverage
    - Dynamic import usage
    - Image optimization
    - Font loading strategy
14. **Runtime performance** -- Check for performance antipatterns:
    - N+1 query patterns
    - Missing database indexes (if schema is accessible)
    - Unnecessary re-renders (React)
    - Memory leak patterns (event listeners, intervals)
    - Expensive computations without memoization
    - Missing pagination on large data sets
15. **API performance** -- Review API design:
    - Response payload sizes
    - Missing caching headers
    - Over-fetching or under-fetching patterns
    - Connection pooling configuration
    - Timeout handling

### Phase 5: Accessibility Audit
16. **Semantic HTML analysis** -- Check markup quality:
    - Proper heading hierarchy
    - Landmark usage (nav, main, aside, etc.)
    - List markup for list content
    - Table markup for tabular data
17. **Interactive element analysis** -- Check usability:
    - Keyboard navigation support
    - Focus management
    - Touch target sizes
    - Form label associations
    - Error message accessibility
18. **ARIA analysis** -- Check assistive technology support:
    - ARIA role usage and correctness
    - Live region announcements
    - Modal/dialog focus trapping
    - Loading state announcements
19. **Visual analysis** -- Check visual accessibility:
    - Color contrast ratios (WCAG AA: 4.5:1 text, 3:1 UI)
    - Font size minimums (>= 14px body)
    - Motion preferences respected (prefers-reduced-motion)
    - Focus indicator visibility

### Phase 6: Report
20. **Compile findings** -- Aggregate all findings with severity ratings:
    - **Critical**: Security vulnerabilities, data exposure, auth bypass
    - **High**: Performance blockers, major accessibility failures, architectural debt
    - **Medium**: Code quality issues, minor security concerns, missing tests
    - **Low**: Style inconsistencies, minor optimization opportunities
    - **Info**: Suggestions, best practice recommendations
21. **Generate executive summary** -- Produce a high-level health assessment:
    - Overall health score (A-F or numeric)
    - Per-dimension scores
    - Top 5 priority fixes
    - Trend comparison (if previous audit data exists)
22. **Invoke `docs-writer`** -- Format the audit report.
23. **Present findings** -- Deliver the report with actionable next steps.
24. **Suggest remediation plan** -- Invoke `plan` to create a fix plan if the user wants to address findings.

## Severity Matrix

| Dimension | Critical | High | Medium | Low |
|-----------|----------|------|--------|-----|
| Security | Data breach risk, auth bypass | Injection vectors, weak crypto | Missing headers, verbose errors | Outdated non-vulnerable deps |
| Quality | Circular deps, no tests | God objects, no error handling | DRY violations, magic numbers | Naming inconsistencies |
| Performance | Memory leaks, N+1 in loops | Missing indexes, huge bundles | Missing memoization | Minor optimization opportunities |
| Accessibility | No keyboard access, missing alt | No focus management, low contrast | Missing ARIA labels | Suboptimal heading order |

## Usage

Use Audit when you want a comprehensive understanding of a codebase's health. It's especially valuable before major releases, after inheriting a codebase, or on a regular cadence (monthly/quarterly).

**Best for:**
- Pre-release quality gates
- Codebase health assessments
- New team member onboarding (to understand tech debt)
- Compliance and security reviews
- Post-incident reviews
- Regular health checkups

**Not ideal for:**
- Building features (use `cook`)
- Fixing specific bugs (use `debug` + `fix`)
- Reviewing a single PR (use `code-review`)

## Examples

### Example 1: Full audit
```
User: /audit Run a full audit on this codebase

Audit workflow:
1. scout -> Inventory: 342 files, 18 deps, 67% test coverage
2. Security -> 2 critical (exposed API key in config, SQL injection in search),
              4 medium (missing rate limiting, verbose error messages)
3. Quality -> 1 high (circular dependency in models/), 8 medium (DRY violations),
             12 low (naming inconsistencies)
4. Performance -> 1 high (N+1 in user list endpoint), 3 medium (no code splitting)
5. Accessibility -> 2 high (no keyboard nav on modal, missing form labels),
                   5 medium (low contrast on secondary text)
Report: Overall score C+, 2 critical security fixes needed immediately
```

### Example 2: Security-focused audit
```
User: /audit Security audit only, we're preparing for SOC 2

Audit workflow:
1. scout -> Full codebase inventory
2. Security deep dive -> All 5 security sub-phases with extra scrutiny
3. Report -> Security-specific findings with compliance mapping
4. Suggest -> Plan for remediating all findings before SOC 2 audit
```

### Example 3: Performance audit
```
User: /audit Our app is slow, audit the performance

Audit workflow:
1. scout -> Inventory with focus on bundle size, API routes, DB queries
2. Performance deep dive -> Bundle analysis, runtime patterns, API review
3. Report -> Ranked performance findings with estimated impact
4. Suggest -> Top 5 optimizations with expected improvement
```

## Guardrails

- **Read-only by default.** Audit reports findings but does not change code unless explicitly asked.
- **Always complete the full scope.** If the user asks for a "full audit," run all four dimensions.
- **Severity must be justified.** Every finding needs a clear explanation of why it's rated at that severity.
- **Findings must be actionable.** Every finding needs a remediation recommendation.
- **No false positives.** Verify findings before reporting. A false alarm erodes trust.
- **Respect scope constraints.** If the user says "security only," don't report code quality issues (but mention if you notice critical non-security issues).
- **Maintain confidentiality.** If the audit finds secrets, report their presence without displaying the actual values.