# What Does the /ponytail-audit Command Do? Repository-Wide Over-Engineering Detection

> Learn what the /ponytail-audit command does. This tool scans your repository for over-engineered code, identifies dead code, and suggests simplifications without making changes.

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

---

**The `/ponytail-audit` command is a built-in skill of the Ponytail agent that performs a read-only, repository-wide scan for over-engineered code patterns, generating a ranked list of opportunities to delete dead code, replace custom implementations with standard library equivalents, and simplify abstractions without automatically applying any changes.**

The `/ponytail-audit` command is part of the open-source [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) repository, an AI-powered code review system. Unlike diff-based reviews, this command evaluates your entire codebase to identify architectural bloat and speculative complexity.

## How the /ponytail-audit Command Works

The command operates through a three-stage pipeline: registration, skill delegation, and pattern analysis.

### Command Registration and Routing

Ponytail registers the `/ponytail-audit` command in the VS Code extension layer. In [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js), the system maps the command name to its handler using the `pi.registerCommand` method:

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

```

When invoked, the handler forwards the request to the skill layer by sending the alias `/skill:ponytail-audit`. This routing mechanism separates the UI command surface from the core audit logic.

### Skill Execution and Scanning

The actual audit logic resides in [`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md) and leverages the same detection engine as `ponytail-review`, but with a critical distinction: **it scans the entire repository tree instead of only the current diff**. The skill walks every file in the codebase, applying heuristics to detect five specific categories of over-engineering.

## Detected Over-Engineering Patterns

The `/ponytail-audit` command categorizes findings into five distinct tags, each targeting a specific anti-pattern:

- **`delete:`** Identifies dead code, unused feature flags, and speculative implementations that serve no current purpose.
- **`stdlib:`** Flags hand-rolled utilities that duplicate functionality already present in the language's standard library.
- **`native:`** Detects dependencies or wrapper layers that replicate capabilities built into the target platform.
- **`yagni:`** (You Aren't Gonna Need It) Highlights abstractions with single implementations and no polymorphic requirements.
- **`shrink:`** Points to verbose implementations that can be expressed more concisely without losing clarity.

Each finding includes the file path and a brief description of the optimization opportunity.

## Output Format and Interpretation

Results follow a structured single-line format designed for quick parsing:

```text
delete  unused-debug-flag.  . [src/utils/debug.js]
stdlib  custom-deep-clone.  JSON.parse(JSON.stringify(...)). [src/helpers/clone.js]
yagni   single-implementation-service.  . [src/services/uniqueService.js]

```

After listing all findings, the command emits a summary line quantifying the potential savings:

```text
net: -57 lines, -4 deps possible.

```

If the audit finds no optimization opportunities, it returns the message **"Lean already. Ship."** indicating the codebase has minimal architectural debt.

## Practical Usage Examples

Invoke the command directly in a chat session:

```markdown
/ponytail-audit

```

For programmatic access within scripts or REPL environments, trigger the command via the Ponytail API:

```javascript
pi.runCommand("ponytail-audit")

```

The command is **read-only**; it reports findings but does not modify files. To act on recommendations, developers must manually edit code or invoke targeted refactoring commands.

## Summary

- The `/ponytail-audit` command scans entire repositories for over-engineering, unlike diff-limited reviews.
- It detects five specific pattern types: **delete**, **stdlib**, **native**, **yagni**, and **shrink**.
- Registration occurs in [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js), while logic resides in [`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md) and [`commands/ponytail-audit.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-audit.toml).
- Output includes ranked findings with estimated line and dependency reductions.
- The audit is strictly read-only and never applies automatic changes.

## Frequently Asked Questions

### Does /ponytail-audit modify my code automatically?

No. The `/ponytail-audit` command is strictly read-only. It analyzes the codebase and reports opportunities for simplification, but users must manually implement changes or use other Ponytail commands (such as `/ponytail-review` on specific diffs) to perform actual refactoring.

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

`/ponytail-review` analyzes only the current diff or staged changes, providing feedback on new code. `/ponytail-audit` reuses the same detection logic but scans the **entire repository tree**, evaluating existing legacy code for accumulated over-engineering and technical debt.

### How does the audit rank its findings?

Findings are ranked by the estimated size of the reduction. The command calculates potential line savings and dependency removals, presenting higher-impact optimizations first. The final summary line aggregates these metrics into a net reduction estimate (e.g., `net: -42 lines, -3 deps possible`).

### Where is the /ponytail-audit command defined in the source code?

The command registration appears in [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js), which maps the command to the skill system. The audit logic and LLM prompts are defined in [`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md) and [`commands/ponytail-audit.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-audit.toml), respectively. The underlying detection engine is shared with [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md).