# How to Use the ponytail-audit Skill for Repository-Wide Over-Engineering Detection

> Discover how to use the ponytail-audit skill to scan your repository for over-engineered code. Get suggestions for deletions and simplifications without automatic file modification.

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

---

**The ponytail-audit skill is a built-in Ponytail command that performs a repository-wide scan to identify and rank over-engineered code patterns, suggesting deletions, standard library replacements, and simplifications without automatically modifying files.**

The [ponytail-audit](https://github.com/DietrichGebert/ponytail) skill provides a one-shot audit capability for the Ponytail framework, allowing developers to analyze entire codebases for complexity that violates the YAGNI (You Aren't Gonna Need It) principle. Unlike standard code reviews that focus on bugs or security vulnerabilities, this skill specifically targets unnecessary abstractions, redundant dependencies, and opportunities to leverage native platform features according to the DietrichGebert/ponytail source code.

## Architecture of the ponytail-audit Skill

The ponytail-audit skill consists of three integrated components that handle definition, registration, and execution.

### Skill Definition in SKILL.md

The skill manifest at [`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md) defines the audit's purpose, tags, hunt criteria, output format, and operational boundaries. This markdown file declares the five classification tags used during analysis: **delete**, **stdlib**, **native**, **yagni**, and **shrink**.

### Command Registration in pi-extension/index.js

In [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js), the Ponytail extension system registers the command name `ponytail-audit` (and the alias `ponytail-audit`) and maps it to the generic skill handler via the `/skill:ponytail-audit` route. The registration logic forwards user invocations to the core audit engine while preserving command context.

### Core Audit Logic via ponytail-review

The actual analysis executes through the **ponytail-review** module with the "repo-wide" flag enabled. As implemented in the core source, the engine traverses the file tree, applies tag-based heuristics, ranks findings by impact, and calculates potential line and dependency reductions.

## How to Run the ponytail-audit Skill

You can invoke the skill through chat interfaces, programmatically, or via command line.

### Chat Interface Invocation

In supported chat environments (Hermes, Qoder, etc.), trigger the audit with the forward-slash command or its alias:

```text
User: /ponytail-audit
Bot:  delete unused_logger. Remove. [src/logger.js]
      stdlib json_parse. Use JSON.parse(). [src/util.js]
      net: -12 lines, -2 deps possible.

```

### Command Line Usage

Use the Ponytail launcher to execute the audit directly from your terminal:

```sh

# The `ponytail` launcher forwards the sub-command to the skill

ponytail audit

```

### Programmatic Execution in Node.js

For custom integrations, register and call the skill through the Ponytail extension object following the pattern in [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js):

```js
// Register the command
pi.registerCommand('ponytail-audit', {
  description: 'Run /skill:ponytail-audit',
  handler: (_args, ctx) => sendAlias('/skill:ponytail-audit', '', ctx)
});

// Execute the audit
await pi.runCommand('ponytail-audit', '', ctx);

```

## Understanding the Audit Output Format

The ponytail-audit skill returns findings in a standardized, machine-readable format:

```

<tag> <what to cut>. <replacement>. [path]
net: -<N> lines, -<M> deps possible.

```

Each finding follows this structure:

- **Tag**: Classifies the issue as `delete`, `stdlib`, `native`, `yagni`, or `shrink`
- **What to cut**: Specific component or pattern identified for removal
- **Replacement**: Recommended alternative or "Remove" if deletion suffices
- **Path**: File location in brackets `[src/file.js]`
- **Net impact**: Summary of line count and dependency reductions possible

## Scope and Boundaries of ponytail-audit

The skill operates strictly as an **over-engineering** detector. It does not identify bugs, security vulnerabilities, or performance bottlenecks—those require a standard `/ponytail-review` pass. The audit runs as a **one-shot** operation: it generates the report without applying fixes automatically.

To terminate the skill's active mode, issue the command `stop ponytail-audit` or switch back to normal mode in your interface.

## Summary

- The **ponytail-audit** skill performs repo-wide scans for over-engineered code patterns in the DietrichGebert/ponytail framework
- Three components power the skill: the [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) manifest, registration logic in [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js), and the core **ponytail-review** engine
- Invoke via `/ponytail-audit` (or the alias `ponytail-audit`) in chat, `ponytail audit` in CLI, or `pi.runCommand()` programmatically
- Output uses five tags (`delete`, `stdlib`, `native`, `yagni`, `shrink`) to categorize simplification opportunities with line and dependency impact metrics
- The skill is read-only and excludes security, bug, and performance analysis

## Frequently Asked Questions

### How do I stop the ponytail-audit skill once started?

To exit the skill's dedicated mode, type `stop ponytail-audit` in your chat interface or explicitly switch back to normal mode. The skill runs as a one-shot audit, so it will automatically complete after generating the report, but the mode persists until you issue the stop command or change contexts.

### What is the difference between ponytail-audit and ponytail-review?

While **ponytail-review** handles general code reviews including bugs and security issues, **ponytail-audit** specifically targets over-engineering through a repository-wide lens. The audit skill uses the same core engine as the review skill but activates the "repo-wide" flag and filters for YAGNI violations, unnecessary abstractions, and standard library replacement opportunities only.

### Can ponytail-audit automatically fix the issues it finds?

No, the ponytail-audit skill is strictly read-only and generates reports without modifying source files. As implemented in the DietrichGebert/ponytail source code, the skill produces ranked findings for developer review but requires manual implementation of the suggested deletions, replacements, or simplifications.

### What do the five audit tags mean?

The classification tags defined in [`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md) represent specific over-engineering categories: **delete** identifies removable dead code; **stdlib** suggests replacing custom implementations with standard library functions; **native** recommends platform-specific native features over abstractions; **yagni** flags speculative complexity violating the "You Aren't Gonna Need It" principle; and **shrink** targets code that can be reduced in scope or size.