What Does the `/ponytail-review` Command Do? A Complete Guide to Ponytail's Over‑Engineering Detector

The /ponytail‑review command analyzes code diffs to identify and suggest removals of over‑engineered code—including dead code, reinventions of standard libraries, unnecessary dependencies, and bloated abstractions.

The ponytail‑review command is a built‑in utility in the Ponytail agent framework (maintained by DietrichGebert/ponytail) that performs automated code reviews focused exclusively on deletion opportunities. Unlike traditional linters or correctness checks, this command asks a single question: what can be cut?

How the /ponytail-review Command Works

When you run ponytail review, the framework collects the current diff—whether unstaged changes, staged index, or a specific commit—and ships it to a configured LLM along with a specialized prompt template. The LLM returns a line‑by‑line analysis tagged according to five categories of removable code.

The command's behavior is defined in [commands/ponytail-review.toml](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml):

description = "Review changes for over-engineering, what can be deleted"
prompt = "Review the current code changes for over‑engineering only, not correctness. One line per finding: L<line>: <tag> <what to cut>. <replacement>. Tags: delete (dead code/speculative feature), stdlib (reinvented standard library), native (dependency doing what the platform does), yagni (abstraction with one implementation), shrink (same logic, fewer lines). End with the net lines removable. If nothing to cut: 'Lean already. Ship.'"

The Five Review Tags Explained

Each finding uses a tag to categorize the type of over‑engineering detected:

Tag	Meaning	Example
delete	Dead code or speculative features	Unused functions, debug statements, commented‑out blocks
stdlib	Reinvented standard‑library functionality	Custom flatten instead of Array.prototype.flat()
native	Dependencies duplicating platform capabilities	External fetch library when native fetch exists
yagni	Unnecessary abstraction ("You Aren't Going to Need It")	Interface with only one implementation
shrink	Same logic expressible in fewer lines	Verbose conditionals that ternary operators can replace

The strict output format (L<line>: <tag> <what to cut>. <replacement>.) ensures parseable, actionable results.

Running the /ponytail-review Command

Invoke the command from any directory where Ponytail is initialized:

# Review unstaged changes in the current repository

ponytail review

# Review a specific commit

ponytail review --commit HEAD~1

# Review only staged (index) changes

ponytail review --staged

# Use a specific LLM model

ponytail review --model gpt-4o-mini

Sample Output from /ponytail-review

When the LLM detects removable code, output follows this pattern:

L27: delete console.log("debug").   // remove debugging statement
L42: stdlib replace with Array.prototype.flat().   // use built‑in flatten
L58: native drop external‑fetch dependency.   // native fetch API already available
...
Total removable lines: 3

If the diff is already minimal:

Lean already. Ship.

Key Implementation Files

The /ponytail-review command spans three architectural layers in the Ponytail repository:

• [commands/ponytail-review.toml](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml) — Defines the prompt template and description that shape the LLM's review behavior.

• [hooks/ponytail-runtime.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) — Core runtime that gathers diffs via Git operations and orchestrates LLM calls.

• [tests/commands.test.js](https://github.com/DietrichGebert/ponytail/blob/main/tests/commands.test.js) — Integration tests verifying output format compliance and tag recognition.

When to Use /ponytail-review vs. Other Tools

Tool Type	Focus	/ponytail-review Difference
Linters (ESLint, Pylint)	Syntax and correctness	Ignores correctness; targets bloat
Type checkers	Type safety	No type analysis performed
Security scanners	Vulnerability detection	No security assessment
Traditional code review	General quality	Solely optimized for deletion

Run /ponytail-review before human review to preemptively strip noise from pull requests.

Summary

• The /ponytail‑review command is a deletion‑focused code review utility in the Ponytail framework.
• It analyzes diffs using five tags: delete, stdlib, native, yagni, and shrink.
• Configuration lives in commands/ponytail-review.toml with a strict prompt enforcing parseable output.
• Runtime execution is handled by hooks/ponytail-runtime.js, which feeds Git diffs to configured LLMs.
• Empty results return the celebratory message: "Lean already. Ship."

Frequently Asked Questions

What makes /ponytail-review different from a regular linter?

Linters enforce correctness and style rules; /ponytail-review exclusively hunts for removable code. It does not flag syntax errors, type mismatches, or security issues—only opportunities to delete without breaking functionality.

Can I customize the tags or prompt in /ponytail-review?

Yes. The prompt template in [commands/ponytail-review.toml](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml) is fully editable. Modify tag definitions, add new categories, or adjust output formatting to match your team's conventions.

Does /ponytail-review require an internet connection?

Yes. The command relies on Ponytail's LLM integration (OpenAI, Claude, Gemini, etc.). All diff analysis is performed remotely based on the prompt sent by [hooks/ponytail-runtime.js](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js).

How does /ponytail-review handle large diffs?

The runtime in ponytail-runtime.js passes the complete diff to the configured LLM. Token limits apply based on your provider and model—very large changes may need to be split across multiple invocations using --commit ranges.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}