# How to Use the `/ponytail-review` Command: Over-Engineering Detection in Ponytail

> Learn to use the /ponytail-review command to detect and simplify over-engineered code. This powerful tool scans your Git diff, suggesting deletions and improvements with specific tags.

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

---

**The `/ponytail-review` command scans your Git diff or specified files to identify unnecessary complexity, suggesting deletions and simplifications using five specific tags.**

The `/ponytail-review` command is one of six built-in skills in the [Ponytail](https://github.com/DietrichGebert/ponytail) open-source project designed to detect over-engineering. When invoked, it analyzes code for bloat patterns and returns actionable, line-specific recommendations for simplification.

## What Is the ponytail-review Command?

The `ponytail-review` command is a specialized **over-engineering review skill** that focuses exclusively on what can be removed rather than what can be added. Unlike general code reviewers, this command employs a specific taxonomy of anti-patterns—tagged as `delete`, `stdlib`, `native`, `yagni`, and `shrink`—to categorize unnecessary complexity. The skill is defined in [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md), which establishes the output format and scoring rules that the LLM must follow when generating recommendations.

## How the ponytail-review Command Works

The command operates through a three-layer architecture that bridges user input to LLM analysis.

### Skill Definition Layer

The human-readable behavior and output constraints reside in [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md). This file defines the five tags that categorize over-engineering patterns:

- **`delete`** – Code that should be removed entirely
- **`stdlib`** – Custom implementations replaceable with standard library features  
- **`native`** – Third-party dependencies replaceable with native APIs
- **`yagni`** – Premature abstraction violating the "You Aren't Gonna Need It" principle
- **`shrink`** – Verbose constructs that can be compressed into fewer lines

The SKILL.md file also mandates a one-line output syntax and specifies that when no issues are found, the response must be "Lean already. Ship."

### Command Registration Layer

The slash command is registered through the Pi extension API in [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js). The registration maps the user-facing command to an internal skill alias:

```javascript
pi.registerCommand("ponytail-review", {
  description: "Run /skill:ponytail-review",
  handler: (_args, ctx) => sendAlias("/skill:ponytail‑review", "", ctx),
});

```

The `handler` function calls `sendAlias()` to route the command to the internal skill system. This abstraction allows the skill to be invoked through multiple interfaces while maintaining a single execution path.

### Command-to-Skill Mapping

The static prompt that drives the LLM analysis lives in [`commands/ponytail-review.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml). This TOML configuration file contains the system prompt instructing the model to "review diffs for unnecessary complexity" and enforce the output format defined in the SKILL markdown. The [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) file injects this prompt into the LLM input pipeline when the command is detected, while [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) activates Ponytail mode if not already enabled.

## Using ponytail-review in Practice

The command supports multiple invocation patterns depending on your environment and targeting needs.

### Basic Invocation

In chat interfaces or IDEs supporting Ponytail, type:

```text
/ponytail-review

```

For hosts requiring a prefix (such as Devin CLI), use the dollar syntax:

```bash
$ponytail-review

```

### Targeting Specific Files

To analyze a particular file or directory rather than the entire diff:

```text
/ponytail-review src/app.js

```

This scans only the specified path for over-engineering patterns while ignoring other changes in the working directory.

### Programmatic Usage

You can trigger the review programmatically using the Pi extension API:

```javascript
// Assuming `pi` is the Ponytail extension API instance
pi.runCommand("ponytail-review");   // triggers the skill

```

This method is used by agent integrations listed in [`plugin.yaml`](https://github.com/DietrichGebert/ponytail/blob/main/plugin.yaml), including Qoder and Grok, which consume the skill through the standardized extension interface.

## Understanding the Output Format

The `ponytail-review` command returns a concise, line-numbered report following the format specified in [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md). A typical output looks like:

```

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.
net: -52 lines possible.

```

Each line follows the pattern `Location: tag: Description. Replacement rationale.` The final line provides a net lines-of-code impact estimate.

## Summary

- **`/ponytail-review`** is a specialized skill in the DietrichGebert/ponytail repository that identifies over-engineering through five specific anti-pattern tags.
- The command architecture separates concerns between the skill definition ([`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md)), command registration ([`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js)), and prompt configuration ([`commands/ponytail-review.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml)).
- Invocation supports both interactive chat syntax (`/ponytail-review`) and programmatic API calls (`pi.runCommand("ponytail-review")`).
- Output follows a strict one-line-per-issue format indicating line numbers, tags, and net code reduction potential.

## Frequently Asked Questions

### How do I trigger ponytail-review in different host environments?

The command adapts to host-specific invocation patterns. In standard chat interfaces, use `/ponytail-review`. In Devin CLI, prefix with a dollar sign: `$ponytail-review`. For Codex and similar agents, use `@ponytail-review` as shown in the repository's README quick-reference table.

### What does "Lean already. Ship." mean in the output?

This message appears when the `ponytail-review` skill cannot identify any over-engineering patterns in the analyzed code. According to the Boundaries section of [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md), this is the required response when no improvements can be suggested, indicating the code is already minimal.

### Can I use ponytail-review on unstaged changes only?

Yes. The command scans the current Git diff by default, which includes both staged and unstaged changes. To review a specific subset, pass a file path argument such as `/ponytail-review src/utils.js` to limit analysis to that target.

### How does ponytail-review differ from general code review tools?

While standard linters check for style and correctness, `ponytail-review` exclusively targets **removable complexity**. It uses the five-tag taxonomy (`delete`, `stdlib`, `native`, `yagni`, `shrink`) to categorize specific types of bloat, and it quantifies potential line reductions rather than just flagging issues.