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

> Discover what the /ponytail-review command does. This guide explains how Ponytail detects and helps remove over-engineered code, dead code, and unnecessary dependencies in your diffs.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: how-to-guide
- Published: 2026-09-07

---

**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)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml):

```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:

```bash

# 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)](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)](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)](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`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml)** with a strict prompt enforcing parseable output.
- Runtime execution is handled by **[`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/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)](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)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js).

### How does `/ponytail-review` handle large diffs?

The runtime in [`ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/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.