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

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 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, the system maps the command name to its handler using the pi.registerCommand method:

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

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:

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:

/ponytail-audit

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

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, while logic resides in skills/ponytail-audit/SKILL.md and 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, which maps the command to the skill system. The audit logic and LLM prompts are defined in skills/ponytail-audit/SKILL.md and commands/ponytail-audit.toml, respectively. The underlying detection engine is shared with skills/ponytail-review/SKILL.md.

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