# How to Use the ponytail-review Skill: Detecting Over-Engineering in Code Diffs

> Learn how to use the ponytail-review skill to detect over-engineering in code diffs. Get instant simplification suggestions with this powerful Hermes plugin. Effortlessly improve your code quality.

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

---

**The ponytail-review skill is a Hermes plugin that scans code diffs for over-engineering and returns one-line simplification suggestions via slash command `/ponytail-review` or by setting the runtime mode to "review".**

The **ponytail-review skill** is part of the DietrichGebert/ponytail repository, a lightweight code review automation tool designed to identify unnecessary complexity in pull requests. This specialized skill focuses exclusively on detecting bloat, abstraction overuse, and dependency-heavy solutions that could be replaced with simpler alternatives.

## Architecture and Source Code Flow

The skill operates through a streamlined pipeline defined in the core plugin entry point. Understanding the internal routing helps diagnose activation issues and customize behavior.

**Core Components**

- **[`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md)** — Contains the human-readable specification, output format constraints, tags, and examples that guide the LLM’s review behavior.
- **`__init__.py:95-100`** — The `register` function scans the `skills/` directory and auto-registers each [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) with the Hermes gateway.
- **`__init__.py:14-16`** — The `SKILL_COMMANDS` table maps the short command name `ponytail-review` to its description for CLI discovery.
- **`__init__.py:150-165`** — The `rewrite_gateway_command` function detects `/ponytail-review` messages, validates ACL permissions, and rewrites them into a skill prompt.
- **`__init__.py:31-38`** — The `_skill_prompt` builder constructs the final LLM instruction: "Load and follow the Hermes plugin skill `ponytail:review` ..."
- **`__init__.py:110-116`** — The `build_injected_context` function reads [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) and injects it as system context when the runtime mode is set to **review**.

## How to Activate the ponytail-review Skill

You can invoke the skill through two primary mechanisms depending on your integration preference.

### Via Slash Command

Type the following in any Hermes-compatible chat interface:

```text
/ponytail-review

```

The `rewrite_gateway_command` function in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py) intercepts this message, verifies user permissions, and transforms the command into a structured prompt. Optional arguments appended after the command are passed verbatim to the skill context.

### Via Runtime Mode

Set the Ponytail runtime to **review** mode to enable continuous scanning without repeated slash commands:

```text
/ponytail review

```

When activated, `build_injected_context` (lines 110-116) automatically loads [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) and prepends it to every subsequent LLM turn. This mode is ideal for CI pipelines or long-running review sessions.

## Understanding the Output Format

The **ponytail-review skill** enforces a strict one-line-per-finding format to ensure machine-parseable results and concise human reading.

**Syntax Pattern**

```

<file>:L<line>[-<endline>]: <tag> <description>. <replacement>.

```

**Valid Tags**

- **`delete:`** — Remove the identified code entirely.
- **`stdlib:`** — Replace with a standard library equivalent.
- **`native:`** — Swap for a native browser or runtime API.
- **`yagni:`** — Remove premature abstraction (You Aren't Gonna Need It).
- **`shrink:`** — Reduce verbosity or consolidate logic.

**Example Output**

```

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.

```

If no issues are detected, the skill returns the termination phrase:

```

Lean already. Ship.

```

## Practical Implementation Examples

### Triggering a Review Programmatically

```python

# Assuming `gateway` is a Hermes-compatible client

gateway.send_message("/ponytail-review")

# Internally calls rewrite_gateway_command and injects the skill prompt

```

### Enabling Review Mode in Python

```python
from ponytail import _current_mode, build_injected_context

# Force review mode for the next LLM invocation

_current_mode = "review"
context = build_injected_context("review")
print(context)  # Outputs full SKILL.md content ready for LLM injection

```

### Parsing Review Findings

```python
import re

def parse_findings(text: str):
    pattern = re.compile(
        r"^(?:(?P<file>[^:]+):)?L(?P<start>\d+)(?:-(?P<end>\d+))?:\s*"
        r"(?P<tag>\w+):\s*(?P<what>.+?)\.\s*(?P<replacement>.+)$"
    )
    findings = []
    for line in text.splitlines():
        match = pattern.match(line.strip())
        if match:
            findings.append(match.groupdict())
    return findings

# Example usage

output = "L12-38: stdlib: 27-line validator class. Use regex."
results = parse_findings(output)

```

## Summary

- The **ponytail-review skill** specializes exclusively in detecting over-engineering patterns such as unnecessary abstractions, heavy dependencies, and verbose implementations.
- Activation occurs via **`/ponytail-review`** slash command (processed by `rewrite_gateway_command` in `__init__.py:150-165`) or by switching the runtime to **review** mode.
- Output follows a strict one-line format using tags (`delete`, `stdlib`, `native`, `yagni`, `shrink`) defined in [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md).
- The skill architecture relies on automatic registration through `__init__.py:95-100` and context injection via `build_injected_context` when in review mode.
- Results are deterministic and parseable, returning "Lean already. Ship." when no simplifications are needed.

## Frequently Asked Questions

### What triggers the ponytail-review skill automatically?

The skill triggers automatically when a user sends the `/ponytail-review` slash command or when the Ponytail runtime mode is explicitly set to "review" via the configuration or CLI. In both cases, the `build_injected_context` function loads [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) and injects it as the LLM's system prompt.

### How do I interpret the "yagni" tag in the output?

The **`yagni`** tag stands for "You Aren't Gonna Need It" and flags premature abstraction layers—such as abstract base classes with only one concrete implementation or unused interface definitions. The recommendation is to inline the code until a genuine second use case emerges that justifies the abstraction overhead.

### Can I customize the tags or output format of the ponytail-review skill?

The output format is rigidly defined in [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) to ensure compatibility with parsing tools. While you cannot modify the core tags (`delete`, `stdlib`, `native`, `yagni`, `shrink`) without forking the repository, you can pass additional context arguments after the slash command to guide the LLM's focus toward specific files or patterns.

### Where is the skill configuration stored in the repository?

The skill definition resides in **[`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md)**, which contains the complete prompt engineering specification, examples, and boundary conditions. The registration and routing logic lives in **[`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py)** at the repository root, specifically between lines 14-16 for command mapping and lines 95-100 for skill discovery.