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

> Discover how Ponytail's review mode detects over-engineered code with session-only LLM analysis, offering insights without default configuration changes.

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

---

**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`](https://github.com/DietrichGebert/ponytail/blob/main/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

```text
/ponytail-review src/app.js

```

The LLM responds with categorized findings:

```text
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

```javascript
// 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:

```javascript
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`](https://github.com/DietrichGebert/ponytail/blob/main/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.