# Ponytail Audit > Whole-repo audit for over-engineering: scans the entire codebase for a ranked list of what to delete, simplify, or replace with stdlib/native equivalents. Use when the user says "audit this codebase", "audit for over-engineering", "what can I delete from this repo", "find bloat", "ponytail-audit", or "/ponytail-audit". One-shot report, does not apply fixes. - Skill: `caneff/ponytail-audit` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add caneff/ponytail-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/caneff/ponytail-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: caneff (https://skillmd.com/u/caneff) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/caneff/ponytail-audit --- Over-engineering audit, repo-wide. Scan the whole tree — scope defaults per `~/.agents/skills/all-audits/SKILL.md`'s Scope section. Rank findings biggest cut first. Skip vendored, generated, and dependency trees (`node_modules`, `dist`, `.venv`, `vendor`, build output, lockfiles) and any `.git/` or `worktrees/` tree — audit only the project's own tracked source. ## Tags - `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing. - `stdlib:` hand-rolled thing the standard library ships. Name the function. - `native:` dependency or code doing what the platform already does. Name the feature. - `yagni:` abstraction with one implementation, config nobody sets, layer with one caller. - `shrink:` same logic, fewer lines. Show the shorter form. - `bloat:` a function or class ruff's `PLR` rules flag as oversized — too many branches (`PLR0912`), arguments (`PLR0913`), statements (`PLR0915`), or public methods (`PLR0904`). Replacement: split it along its actual seams. ## Hunt Deps the stdlib or platform already ships, single-implementation interfaces, factories with one product, wrappers that only delegate, files exporting one thing, dead flags and config, hand-rolled stdlib, long-method/large-class bloaters. Verify before you list — grep the symbol across the tree (excluding tests) and confirm zero real callers, so a finding survives a skeptic. A dead export whose only caller is its own test still counts; say so. **Mechanical lead for `bloat:`.** Run `uvx ruff check --select PLR0912,PLR0913,PLR0915,PLR0904 --output-format json ` first — a candidate list, not a verdict, the mechanical-scan role `audit.py` plays for `test-audit`. Read each hit same as any other tag: a large function whose branches are one honest dispatch, not tangled special-casing, is a `Deliberately leaving alone`. Card it the usual way — tag `bloat:`, the rule code named in the one-sentence problem, files, before/after. ## Present the audit as an HTML report Deliver the audit as a **single self-contained HTML file**, the same way `/improve-codebase-architecture` and `/thermo-nuclear-code-quality-review` do — not as a wall of terminal one-liners. Write the report to a fresh `/ponytail-audit-/report.html` so nothing lands in the repo, then deliver it per `~/.agents/skills/ponytail-audit/HTML-REPORT.md` — tmpdir resolution, copying the assets beside it, opening it, and handing off the absolute path all live there. The report is styled with the **visual-teach** design system — vendored `vt-*` components and `--vt-*` theme tokens, the same system the teaching lessons and the two sibling review skills use. It loads **no external host**: CSS, JS, Prism grammars, and Mermaid all come from local files copied beside the report, so it opens offline and carries a working light/dark mode. Show each cut as a **before/after** — the code as it stands beside the one-line replacement (or `— gone —` for a straight delete). Reach for a `vt-mermaid` graph only when the cut is a shape — a one-implementation seam collapsing into its sole caller, a wrapper chain flattening — not for every card. The report leads with a one-line **verdict**, then a **top cut** headline card for the single biggest reduction, then the ranked finding cards (each with a tag badge, a line-count chip, the files, the one-sentence problem, the before/after, and win bullets), and closes with a **Deliberately leaving alone** list so the reader sees what was considered and consciously kept — the real abstractions and the deliberate redundancy. Ranking is unchanged: **biggest cut first.** The header carries the only metric that matters — `net: - lines, - deps possible` — and each card its own line count. Nothing to cut: a one-card report whose verdict is `Lean already. Ship.` See `~/.agents/skills/ponytail-audit/HTML-REPORT.md` for the card anatomy and the tag→badge palette, and `~/.agents/skills/all-audits/harness/HTML-REPORT.md` for the shared scaffold and the `copy_assets` asset step. ## Write the findings in plain language The HTML is a deliverable a reader judges — write every finding in plain, present-tense sentences a maintainer understands on the first read. The tags (`delete:`/`stdlib:`/…) and the steering metaphors ("bloat", "dead flexibility") are for you; the card prose says what is actually true and what it costs. "This class is never constructed outside its own test" beats "speculative YAGNI cruft". State the replacement concretely — the stdlib function by name, the one-line form, or "nothing". ## Boundaries Complexity only. Correctness bugs, security holes, and performance go to a normal review pass, not this one. A single smoke test or `assert`-based self-check is the minimum, not bloat — never flag it for deletion. Lists findings, applies nothing. One-shot.