How Ponytail Review Mode Works: Session‑Only Over‑Engineering Detection

Ponytail's review mode is a session‑only analysis tool that detects over‑engineered code through a dedicated LLM skill without persisting as a default configuration.

The Ponytail code‑review assistant provides a specialized review mode for on‑the‑fly analysis of code changes. Unlike the standard runtime levels (off, lite, full, ultra), this mode activates temporary behavior that scans for dead code, reinventions of standard libraries, and unnecessary abstractions. The implementation spans the command dispatcher, mode tracker, instruction generator, and a dedicated markdown skill file.

What Is Ponytail Review Mode?

Review mode is an independent, ephemeral analysis state that operates solely within the current session. It triggers a targeted prompt asking the LLM to evaluate diff content for over‑engineering patterns such as YAGNI violations, redundant wrappers, and custom implementations of native methods.

The mode is explicitly excluded from persistence logic, ensuring it never becomes an accidental default for future sessions.

Session‑Only vs Persistent Modes

Standard Ponytail modes (lite, full, ultra) can be saved as defaults via configuration files. In contrast, review mode is listed in the INDEPENDENT_MODES Set inside hooks/ponytail‑instructions.js, which signals the system to avoid writing it to disk. This design guarantees that invoking /ponytail‑review affects only the immediate command execution.

How Review Mode Executes

The execution flow involves five distinct components that transform a user command into a concise lean‑code report.

Command Registration

The Pi‑extension exposes the review functionality through an alias. In pi‑extension/index.js (lines 149‑151), the extension registers ponytail‑review as a forward to the hidden skill /skill:ponytail‑review. This allows users to type the shorthand while the system routes to the skill‑based implementation.

Mode Detection

When the command reaches the hook layer, hooks/ponytail‑mode‑tracker.js (lines 31‑36) intercepts the input. If the command matches /ponytail‑review or /ponytail:ponytail‑review, the tracker sets the runtime mode variable to the string 'review'. This value exists only in memory for the duration of the request.

Instruction Generation

The getPonytailInstructions() function inside hooks/ponytail‑instructions.js (lines 8‑12) checks the active mode against INDEPENDENT_MODES = new Set(['review']). When the mode is 'review', the generator returns a banner message and a reference to the dedicated skill body:

PONYTAIL MODE ACTIVE — level: review. Behavior defined by /ponytail‑review skill.

This banner instructs the LLM to load the specific instructions defined in the skill file rather than the general‑purpose Ponytail prompts.

The Review Skill Body

The actual analysis logic resides in skills/ponytail/SKILL.md. This markdown file contains a prompt that directs the LLM to examine code changes for over‑engineering only. The prompt enumerates specific tags for classification:

• delete – Dead code removal
• stdlib – Replacing custom logic with standard library equivalents
• native – Using built‑in language features instead of wrappers
• yagni – Removing "You Aren't Gonna Need It" abstractions
• shrink – Condensing verbose implementations

The LLM returns one‑line suggestions per issue followed by a summary count of removable lines.

Execution Flow

1. User invokes /ponytail‑review with a file or diff
2. Mode tracker sets session state to 'review'
3. Instruction generator loads the SKILL.md prompt
4. LLM receives the diff and the over‑engineering detection rules
5. Response is returned as structured text without modifying any config file

Using Review Mode in Practice

You can trigger the analysis via slash command in any supported chat interface or programmatically through the Pi client.

Command Line Invocation

/ponytail-review src/app.js

The LLM responds with categorized findings:

L23: delete – remove unused helper function.
L47: stdlib – replace custom map implementation with Array.prototype.map().
L112: yagni – eliminate abstraction that only wraps a single API call.
Net lines removable: 3

Programmatic Usage via Node.js

// Assuming `pi` is the initialized Ponytail Pi client instance
await pi.runCommand('ponytail-review', 'src/utils.js');

Verifying Non‑Persistence

Attempting to set review mode as a default silently falls back to the built‑in default (typically lite). The enforcement logic in hooks/ponytail‑config.js (lines 17‑22) filters out INDEPENDENT_MODES from persistence operations:

process.env.PONYTAIL_DEFAULT_MODE = 'review';
console.log(pi.getDefaultMode()); // → "lite"

Why Review Mode Cannot Be Set as Default

The ponytail‑config.js hook actively rejects attempts to persist review as a default level. Because the mode consumes additional tokens for analysis and produces specialized output unsuitable for general linting, the architects restricted it to explicit, session‑scoped invocations. This prevents performance overhead and accidental activation during routine development tasks.

Summary

• Ponytail review mode is a session‑only command that analyzes code for over‑engineering patterns without altering persistent configuration.
• The flow routes through pi‑extension/index.js for command registration, ponytail‑mode‑tracker.js for state detection, and ponytail‑instructions.js for banner generation.
• Analysis logic lives in skills/ponytail/SKILL.md, which prompts the LLM to tag issues as delete, stdlib, native, yagni, or shrink.
• The mode is excluded from persistence by the INDEPENDENT_MODES Set, ensuring it never becomes a default runtime level.

Frequently Asked Questions

Can I set review mode as my default Ponytail configuration?

No. Because review is included in the INDEPENDENT_MODES Set within hooks/ponytail‑instructions.js, the configuration hook in hooks/ponytail‑config.js explicitly blocks it from being written to settings. Attempting to set a default will silently fallback to lite or another valid level.

What over‑engineering patterns does review mode detect?

The skill file defines five classification tags: delete for dead code, stdlib for standard library replacements, native for built‑in feature usage, yagni for unnecessary abstractions, and shrink for verbosity reduction. The LLM outputs one‑line suggestions for each match.

How do I invoke review mode programmatically in my application?

Import the Ponytail Pi client and call pi.runCommand('ponytail-review', filePath). This method bypasses shell parsing and directly triggers the mode tracker with the correct session context, returning the structured analysis as a string.

Does review mode modify my source files automatically?

No. Review mode performs read‑only analysis. The LLM generates a report indicating which lines could be removed or refactored, but the user must manually apply the suggested changes; there is no automatic code modification triggered by the ponytail‑review command.

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