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

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

/ponytail-review

The rewrite_gateway_command function in __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:

/ponytail review

When activated, build_injected_context (lines 110-116) automatically loads 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

# 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

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

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.
• 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 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 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, which contains the complete prompt engineering specification, examples, and boundary conditions. The registration and routing logic lives in __init__.py at the repository root, specifically between lines 14-16 for command mapping and lines 95-100 for skill discovery.

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