# What Is the ponytail-debt Command? Technical Debt Tracking for Ponytail > Learn how the ponytail-debt command scans your repo for ponytail: markers to generate a debt ledger, tracking intentional shortcuts and upgrade triggers. - Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) - Tags: documentation - Published: 2026-09-03 --- **The `ponytail-debt` command is a built-in Ponytail skill that scans your repository for `ponytail:` comment markers and generates a debt ledger showing intentional shortcuts, their performance ceilings, and pending upgrade triggers.** The Ponytail repository includes a dedicated command for managing technical debt visibility. The `ponytail-debt` command transforms scattered "later-means-never" comments into a structured inventory of deliberate simplifications. By harvesting markers defined in [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md), it creates an actionable report that prevents deferred work from silently rotting in the codebase. ## How the ponytail-debt Command Works The command operates as a two-phase scanner that converts inline comments into a trackable ledger. ### Scanning for ponytail: Markers When invoked, the command traverses the repository for every comment that follows the **`ponytail:`** convention (for example, `// ponytail: …`). Each marker documents a deliberate shortcut or simplification the developer chose to defer. The comment captures three critical pieces of metadata: - **The simplification** – what was shortcut (e.g., "replace custom loop with Array.map") - **The ceiling** – the limit the shortcut imposes (e.g., `O(n)` complexity or `no-trigger`) - **The upgrade path** – the trigger that should cause the shortcut to be revisited (e.g., "add tests") ### Generating the Debt Ledger After harvesting these markers, the command produces a **read-only debt ledger**—a concise list of "what was simplified, where, and with what pending upgrade." According to the skill definition in [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md), the ledger serves two primary purposes: 1. **Visibility** – it turns hidden comments into an explicit, countable list so technical debt is not forgotten 2. **Actionability** – by highlighting markers tagged with `no-trigger` (lacking an upgrade path), it points developers to shortcuts most at risk of silent rot ## Using the ponytail-debt Command You invoke the skill directly in chat with the Ponytail agent using the forward-slash syntax defined in [`commands/ponytail-debt.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml): ```text /ponytail-debt ``` ### Typical Output Format The command returns a ledger formatted with file paths, line numbers, and metadata: ```text src/utils/helpers.js:23 — replace custom loop with Array.map. ceiling: O(n) upgrade: add tests src/components/Widget.jsx:57 — inline style instead of CSS class. ceiling: no-trigger … <12> markers, <3> with no trigger. ``` ### Persisting the Ledger to File While the command never mutates source files during scanning, you can explicitly request it to write the report to disk. When prompted, confirm the write operation to generate [`PONYTAIL-DEBT.md`](https://github.com/DietrichGebert/ponytail/blob/main/PONYTAIL-DEBT.md): ```text /ponytail-debt # then, when asked, confirm: yes, write to PONYTAIL-DEBT.md ``` This creates a persistent markdown file containing the same debt table for long-term tracking. ## Implementation and Registration The `ponytail-debt` command is registered as a core skill within the Ponytail extension system. Its components are distributed across three key locations: - **[`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md)** – Contains the full skill description, scanning logic, output format specifications, and boundary conditions - **[`commands/ponytail-debt.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml)** – Provides the short description and metadata used by the skill system to recognize the command - **[`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js)** (lines 164-166) – Registers the skill with the Ponytail extension, enabling invocation via `/ponytail-debt` As implemented in `DietrichGebert/ponytail`, this registration ensures the command appears among the six core skills listed in the repository's README. ## Summary - The `ponytail-debt` command scans repositories for `// ponytail:` comment markers that document intentional shortcuts - It extracts **ceilings** (limits) and **upgrade paths** (triggers) from each marker - The output is a **read-only debt ledger** showing file locations, simplifications, and risk levels (notably `no-trigger` tags) - Results can be optionally persisted to [`PONYTAIL-DEBT.md`](https://github.com/DietrichGebert/ponytail/blob/main/PONYTAIL-DEBT.md) for documentation - Skill definition resides in [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md) with registration in [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) ## Frequently Asked Questions ### What does the ponytail-debt command scan for? The command scans for comments following the `ponytail:` convention anywhere in your source code. These comments mark deliberate technical debt items along with their performance ceilings and intended upgrade triggers. ### Does ponytail-debt modify source files? No. The command produces a **read-only report** during normal operation. It only writes to disk if you explicitly confirm writing the ledger to [`PONYTAIL-DEBT.md`](https://github.com/DietrichGebert/ponytail/blob/main/PONYTAIL-DEBT.md) when prompted. ### Where is the ponytail-debt command registered? The command is registered in [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) at lines 164-166, where it is bound to the `/ponytail-debt` invocation path and integrated into the Ponytail extension's skill system. ### How does the ledger help prioritize refactoring? The ledger highlights markers tagged with `no-trigger`, indicating shortcuts that lack a defined upgrade condition. These items represent the highest risk of silent code rot and should be prioritized for immediate refactoring or trigger definition.