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 <scope> 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 <tmpdir>/ponytail-audit-<timestamp>/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: -<N> lines, -<M> 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.