Ponytail Review

Ponytail Review

When to Use

One-shot review focused exclusively on over-engineering. Finds what to delete: reinvented standard library, unneeded dependencies, speculative abstractions, dead flexibility. The diff's best outcome is getting shorter.

Three scopes, picked by argument:

Do not use for correctness bugs, security holes, or performance — route those to @code-review, @code-security-review, or @code-optimization. This lens only hunts complexity.

Core Concepts

One line per finding: location, what to cut, what replaces it. Findings are statements, not questions — never "have you considered whether this class might be more complex than necessary?".

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.

Detailed Topics

Diff scope (default)

Format: L<line>: <tag> <what>. <replacement>. — or <file>:L<line>: ... for multi-file diffs.

End with the only metric that matters: net: -<N> lines possible.

Nothing to cut: Lean already. Ship. — and stop.

Repo scope (repo / "audit")

Same tags, whole tree, ranked biggest cut first: <tag> <what to cut>. <replacement>. [path].

Hunt list: 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.

End with net: -<N> lines, -<M> deps possible.

Debt scope (debt)

Every deliberate ponytail shortcut is marked with a ponytail: comment naming its ceiling and upgrade path. This scope collects them into one ledger so a deferral can't quietly become permanent.

Scan (skip node_modules, .git, build output):

grep -rnE '(#|//) ?ponytail:' .

One row per marker, grouped by file: <file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.

Flag the rot risk: any ponytail: comment that names no upgrade path gets a no-trigger tag — those are the ones that silently rot.

End with <N> markers, <M> with no trigger. Nothing found: No ponytail: debt. Clean ledger.

Examples

❌ "This EmailValidator class might be more complex than necessary, have you considered whether all these validation rules are needed at this stage?"

✅ L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.

✅ L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.

✅ repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.

✅ L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.

✅ L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.

Debt row:

✅ payments/lock.py:17, global lock on charge path. ceiling: single-flight throughput. upgrade: per-account locks if throughput matters.

Boundaries

• Scope: over-engineering and complexity only. Correctness, security, and performance are explicitly out of scope — route them to a normal review pass.
• A single smoke test or assert-based self-check is the ponytail minimum, not bloat — never flag it for deletion.
• Lists findings, applies nothing. One-shot: no flag files, no persistent mode. To persist the debt ledger, ask first, then write it to PONYTAIL-DEBT.md.
• Reverting. "stop ponytail-review" or "normal mode" returns to verbose review style.

Constraints

• Never flag validation, error handling, security measures, accessibility, or the minimum runnable check as over-engineering.
• Never apply the cuts — report only.
• Must end with the score line (net: / marker count) or Lean already. Ship.
• Must keep one line per finding — location, cut, replacement.

Example invocations

• "review this for over-engineering"
• "what can we delete?"
• "find bloat in this repo"
• "/ponytail-review"
• "/ponytail-review repo"
• "/ponytail-review debt"
• "what did ponytail defer?"

Attribution

Based on DietrichGebert/ponytail (MIT license). Consolidates upstream's ponytail-review (diff), ponytail-audit (repo), and ponytail-debt (ledger) skills into a single one-shot skill with a scope argument, following this repository's consolidation convention.