ponytail-audit ยท diff
git:20261005.1b1a0c5 to git:20261008.01cbf81
89 added, 32 removed. Audit A to A.
---
name: ponytail-audit
description: >
- Whole-repo audit for over-engineering. Like ponytail-review, but scans the
- entire codebase instead of a diff: 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.
+ Quality audit of a whole repo: bugs, security holes, what breaks under real
+ load, risky code without tests, slow paths, and what to delete, merge or
+ split. Ranked, each finding explained in plain English. One-shot report,
+ changes nothing. Use for "audit this codebase", "review the whole repo",
+ "find bloat", "what can I delete", /ponytail-audit.
---
- ponytail-review, repo-wide. Scan the whole tree instead of a diff. Rank
- findings biggest cut first.
+ Audit the whole repo like the senior developer who just inherited it and
+ will be paged when it breaks. Order of importance: correct, safe, holds under
+ load, tested, fast, lean. Lean still matters: every extra line must be read,
+ tested and fixed later. This is a report the user asked for, so give it in full.
- ## Tags
+ ## 1. Map first
- Same as ponytail-review:
+ - Audit what the user names: a folder, a package, or the whole repo.
+ Nothing named: the whole repo.
+ - Read the README, the deploy and build config, the dependency list, the
+ entry points (main, routes, handlers, jobs, CLI commands) and the tests.
+ - Find the expected load: one person running a script, or many users and
+ processes at once. Judge scale against that, and say which load you assumed.
+ - Trace the main flows end to end: where data comes in, what is stored,
+ what goes out. Read those paths fully: input from users, money, auth,
+ data writes, background jobs, anything shared between processes.
+ - Big repo: go deep where a mistake costs the most, not file by file. Say
+ which parts you did not read.
- - `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.
- - `reuse:` equivalent helper, util, or pattern already in this repo. Name the path.
- - `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
- - `shrink:` same logic, fewer lines. Show the shorter form.
+ ## 2. Look for
- ## Hunt
+ 1. **Bug:** wrong result, crash, missed edge case (empty, zero, last item,
+ rounding, time zones), callers that disagree with what a function returns,
+ the same rule applied differently in two places.
+ 2. **Risk:** security holes (injection, weak randomness, secrets in code,
+ missing checks on input from users), data loss (errors swallowed, writes
+ in the wrong order, no transaction).
+ 3. **Scale:** fine for one user, wrong for many: check-then-write races, the
+ same work done by every process, memory or lists that only grow, a query
+ per item, O(n^2) on big input, per-process state that must be shared.
+ 4. **Missing test:** risky logic (a branch, a parser, money, security, data
+ writes) with no test that fails when it breaks. One good test, not coverage.
+ 5. **Speed:** big slowdowns are problems. Small wins (work repeated in a hot
+ loop) are suggestions; some software counts every millisecond.
+ 6. **Lean:** code that should not exist or should be smaller.
+ - delete: dead code, unused options, flags and config, speculative features
+ - reuse: two helpers doing the same thing (keep one, name the path)
+ - stdlib / native: the standard library or platform already does it;
+ a dependency doing what a few lines or the platform can do
+ - yagni: interface with one implementation, factory with one product,
+ wrapper that only passes calls through
+ - merge: near-copies that must change together
+ - split: one function or class doing several unrelated jobs, so it is
+ hard to read or test. Split by job, never by line count, and never into
+ helpers that exist only to make a function shorter.
- 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, helpers duplicating an
- equivalent that already lives in this repo.
- Before emitting `delete:`, grep the whole tree for the symbol, including tests,
- fixtures and string or dynamic references.
+ ## 3. Check before you report
- ## Output
+ - Every finding needs a concrete case: "this input or situation leads to this
+ wrong result". No case, no finding.
+ - Before calling code unused, grep the whole tree for it, including tests,
+ fixtures, config, and string or dynamic references.
+ - A shortcut marked with a `ponytail:` comment that names its limit is a
+ decision, not a finding, unless the expected load already crosses it.
+ - Propose the smallest fix that works. Prefer fixes that delete code. Never
+ add layers, frameworks or config the problem does not need.
+ - No style taste, no "consider", no vague worries.
- One line per finding, numbered and ranked: `<N>. <tag> <what to cut>. <replacement>. [path]`,
- so the user can say "fix 2 and 5".
- End with `net: -<N> lines, -<M> deps possible.` Nothing to cut: `Lean already. Ship.`
+ ## 4. Output
- ## Boundaries
+ Very simple English: short sentences, everyday words. Explain a technical
+ term the first time you use it. The reader may never have seen this code.
- Scope: over-engineering and complexity only. Correctness bugs, security holes,
- and performance are explicitly out of scope. Route them to a normal review
- pass. Lists findings, applies nothing. One-shot.
- "stop ponytail-audit" or "normal mode" to revert.
+ Start with `What this repo does:` in two or three sentences, and the load
+ you assumed.
+
+ Then the findings in three groups, most important first, skip empty groups:
+ - **Must fix:** bug, security, data loss, breaks at the expected load.
+ - **Should fix:** risky code without a test, real slowness, duplication, a
+ function that mixes jobs, code that should not exist.
+ - **Nice to have:** small speed-ups, shorter forms.
+
+ Number findings across all groups, so the user can say "fix 2 and 5". At
+ most 20 findings; if you left smaller ones out, say how many.
+ Every finding has all four parts, each one or two short sentences:
+
+ 2. **Orders land on the wrong day** (`billing/close_day.py:L40-52`)
+ - **What this is:** At midnight this job closes the day and bills all orders of that day.
+ - **Problem:** It takes "today" from the server clock, which runs in UTC. An order placed
+ at 00:30 in Berlin is billed on the day before.
+ - **Fix:** Compute the day once in the shop's time zone:
+ `datetime.now(ZoneInfo("Europe/Berlin")).date()`. One line, nothing else changes.
+ - **If we skip it:** Late orders show the wrong date, and accounting fixes them by hand.
+
+ End with:
+ - `Verdict:` one line: healthy, or what to fix first.
+ - `Lean: -<N> lines, -<M> dependencies possible.` when lean findings exist.
+ - `Not checked:` the parts you did not read or could not run.
+
+ Nothing found: `What this repo does:`, then `Healthy. Nothing to fix.` and
+ one line on what you checked.
+
+ One-shot report, changes no code.