---
name: slim-audit
description: Audit codebase for opportunities to reduce lines of code while preserving functionality, performance, and quality
type: analysis
version: v0.1
argument-hint: "[optional: specific package, directory, or file to scope the audit]"
---

# Slim Audit

Audit the codebase, documentation, and specs to identify concrete opportunities to reduce lines of code while maintaining or improving functionality, performance, and code quality. Outputs a prioritized reduction plan with estimated LOC savings.

## Process

1. **Gather project context:**
   - Read `CLAUDE.md`, `README.md`, and project config files to understand conventions, architecture, and constraints.
   - Search for and read project documentation: specs (`specs/`, `spec.md`, `docs/`), changelogs (`CHANGELOG.md`, `tasks/history.md`), ADRs, and design docs.
   - Read `tasks/roadmap.md`, `tasks/todo.md`, `tasks/manual-todo.md`, `tasks/record-todo.md`, and `tasks/recurring-todo.md` if they exist to understand in-progress and advisory work.
   - Build a mental model of **intentional decisions** — patterns, trade-offs, and constraints the team has deliberately chosen.

2. **Determine scope:**
   - If `$ARGUMENTS` specifies a package, directory, or file, scope the audit there.
   - Otherwise, audit the entire project (or all packages in a monorepo).

3. **Analyze for reduction opportunities across these categories:**

   **a. Duplicate and near-duplicate code:**
   - Identify code blocks that are identical or structurally similar (same logic, different names/values).
   - Flag copy-paste patterns across files that could be consolidated into a shared function or module.
   - Look for repeated patterns in tests that could use shared fixtures, helpers, or parameterized tests.

   **b. Over-abstraction and unnecessary indirection:**
   - Wrapper functions/classes that add no logic — they just forward calls to an inner implementation.
   - Adapter or facade layers with a single consumer that could be inlined.
   - Abstract base classes or interfaces implemented by only one concrete class.
   - Factory patterns where a direct constructor or function call would suffice.
   - Middleware or decorator chains that could be collapsed.

   **c. Verbose patterns with idiomatic alternatives:**
   - Manual loops that could be replaced by built-in array/collection methods (`map`, `filter`, `reduce`).
   - Verbose null/undefined checks that could use optional chaining, nullish coalescing, or pattern matching.
   - Hand-rolled utility functions that duplicate standard library or already-imported dependency functionality.
   - Explicit type definitions that could be inferred by the compiler/runtime.
   - Verbose error handling patterns that could use a shared error handler or middleware.

   **d. Redundant logic:**
   - Validation or guard checks already performed upstream (caller validates, callee re-validates).
   - Dead branches in conditionals — conditions that are always true/false given the surrounding code.
   - Redundant type conversions or serialization round-trips.
   - Configuration or initialization code that duplicates framework defaults.

   **e. Hand-rolled implementations replaceable by dependencies:**
   - Custom implementations of functionality provided by an already-imported library (e.g., hand-rolled date formatting when `date-fns` is already in `package.json`).
   - Utility code that reimplements well-tested standard library functions.
   - **Note:** Only suggest replacing with libraries *already in the dependency tree*. Do not suggest adding new dependencies.

   **f. Structural bloat:**
   - Files that exist purely for re-export (barrel files) with no additional logic, where the re-exports could be replaced by direct imports.
   - Excessive file splitting where closely related code (used together, changed together) is scattered across many small files that could be a single cohesive module.
   - Boilerplate-heavy patterns that could be reduced with code generation, decorators, or framework conventions.

4. **Cross-reference findings against documentation:**
   - Before reporting a finding, check if the pattern was an intentional decision documented in specs, ADRs, changelogs, or design docs.
   - If a verbose pattern exists because of a documented constraint (performance, compatibility, readability preference), **do not flag it**. Note it under "Intentional Decisions" instead.
   - If a finding would change externally-visible behavior (API contracts, output format, error messages), flag it as **Behavior Change Risk** rather than a safe reduction.

5. **Estimate impact:**
   - For each opportunity, estimate the approximate LOC reduction (net lines removed after the refactor).
   - Assess risk: Low (pure refactor, no behavior change), Medium (internal behavior change, needs testing), High (external behavior change risk).
   - Assess effort: Small (< 30 min), Medium (1-2 hours), Large (half-day+).

6. **Cross-reference with git:**
   - For flagged areas, check `git log` and `git blame` to understand why the code exists in its current form.
   - Code with recent intentional refactoring history should be flagged with lower confidence.
   - Code untouched for 6+ months with clear reduction paths gets higher priority.

7. **Verify findings (false-positive filter):**
   - Before finalizing, re-read the actual source code for every finding. For each one, confirm:
     - The "duplicate" code is genuinely duplicated — not just structurally similar with important semantic differences.
     - The "unnecessary wrapper" doesn't handle edge cases, logging, error transformation, or other subtle behavior you missed on first read.
     - The "verbose pattern" replacement is actually equivalent — same behavior for all inputs, including edge cases.
     - The "redundant check" is genuinely redundant — the upstream validation actually covers all cases the downstream check handles.
     - The suggested library replacement produces identical output for all relevant inputs.
     - The reduction **preserves all existing functionality** unless the current behavior is a clear, demonstrable bug.
   - **Drop any finding you cannot re-confirm with a second read.** If uncertain, move it to "Needs Investigation" rather than recommending removal.

## Output

### Summary
- **Total opportunities found**: N
- **Estimated total LOC reduction**: ~N lines
- **Risk breakdown**: N low / N medium / N high

### High-Value Reductions (low risk, high LOC savings)
| Location | Category | Current LOC | Est. Savings | Risk | Description |
|----------|----------|-------------|--------------|------|-------------|
| `path/file.ts:20-85` | Duplication | 65 | ~40 | Low | Consolidate into shared helper |

For each high-value finding, include:
- **Current code**: brief description or snippet of the verbose/duplicated pattern
- **Proposed approach**: how to reduce it
- **Why it's safe**: what guarantees functionality is preserved

### Medium-Value Reductions
Same table format — moderate savings or moderate risk.

### Low-Value Reductions
Brief list — small savings, worth tracking but not urgent.

### Behavior Change Risk
Opportunities that would reduce code but may alter externally-visible behavior. Each includes:
- What would change
- Why it might be acceptable (e.g., fixing a likely bug)
- What testing would be needed to confirm safety

### Intentional Decisions (no action)
Verbose patterns that exist for documented reasons — not flagged as issues.

### Needs Investigation
Items that look reducible but have ambiguous usage patterns or unclear intent. Each includes what specifically needs to be investigated.

## Constraints
- Use subagents to parallelize analysis across packages in a monorepo.
- **Never automatically modify code** — only report findings and recommendations.
- **Functionality preservation is the top priority.** Every recommendation must preserve existing behavior unless the current behavior is a clear, demonstrable bug. When in doubt, classify as "Behavior Change Risk" rather than recommending removal.
- Do not recommend reductions that trade LOC for readability — if the verbose version is clearer, it stays.
- Do not recommend adding new dependencies to replace hand-rolled code. Only suggest replacements using libraries already in the dependency tree.
- Do not flag test code for reduction unless the reduction clearly improves test maintainability (e.g., shared fixtures reducing update burden).
- Do not flag configuration files, migration files, or generated code.
- Be specific — always include file paths and line numbers or ranges.
- Every recommendation must include a concrete "proposed approach," not just "simplify this."
- Prefer many small, independent reductions over large sweeping refactors — smaller changes are safer and easier to review.
- If the codebase has no specs or documentation, proceed with the audit but note the absence and increase the confidence threshold for recommendations.


## Alignment Page

When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/slim-audit-{topic}.html`.

## Default Shipping Contract

Follow the shared shipping contract convention in CLAUDE.md.
