# How to Harvest Deferred Ponytail Shortcuts Using the /ponytail-debt Command > Learn to harvest deferred ponytail shortcuts with the /ponytail-debt command. This tool scans comments for constraints and triggers, flagging simplifications needing migration plans in your repository. - Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) - Tags: how-to-guide - Published: 2026-09-09 --- **The /ponytail-debt command performs a repository-wide scan for `# ponytail:` or `// ponytail:` comments, extracts ceiling constraints and upgrade triggers, and generates a ledger report that flags any deferred simplifications lacking migration plans.** Deferred shortcuts in Ponytail are temporary simplifications marked with `# ponytail:` or `// ponytail:` comments that trade immediate velocity for future refactoring. The DietrichGebert/ponytail repository provides the `/ponytail-debt` built-in skill to audit these markers without modifying source files. This command helps teams surface technical debt before it rots. ## What Is the /ponytail-debt Command? The `/ponytail-debt` command is a registered skill in the Ponytail extension that identifies and catalogs all deferred shortcuts across your codebase. According to the skill description in [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md), it executes a targeted search to find comments following the convention: ```python # ponytail: , ``` or its language-specific equivalent using `//` delimiters. The command is wired into the extension via [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) (lines 64-66) and exposes its metadata through [`commands/ponytail-debt.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml). ## How Debt Harvesting Works The command follows a four-stage pipeline to harvest deferred shortcuts: ### Repository-Wide Grep Execution First, the skill runs a recursive grep while ignoring noise directories like `node_modules`, `.git`, and build artifacts. As defined in [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) (lines 15-21), it executes: ```bash grep -rnE '(#|//) ?ponytail:' . ``` This pattern matches both hash-style and slash-style comment prefixes with optional spacing. ### Ledger Row Collection For each match, the extractor parses the file path, line number, simplification description, ceiling limit, and upgrade trigger. The output format (lines 27-33 in [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md)) follows this structure: ``` :, . ceiling: . upgrade: . ``` ### No-Trigger Flagging Any comment omitting the upgrade path receives a `no-trigger` tag. These entries represent high-risk debt that could rot without a defined migration strategy. ### Summary Generation Finally, the command prints the total marker count and the number lacking triggers, or displays a clean-ledger message if none exist (lines 35-38 in [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md)). ## Running /ponytail-debt: Code Examples Basic invocation surfaces all deferred shortcuts: ```bash /ponytail-debt ``` Typical output resembles: ``` src/utils/file.js:42, simplify file path handling. ceiling: O(1) lookup. upgrade: add caching layer. src/components/button.jsx:108, inline style removal. ceiling: inline styles. upgrade: migrate to CSS modules. … 8 markers, 2 with no trigger. ``` To persist the ledger for documentation: ```bash /ponytail-debt > PONYTAIL-DEBT.md ``` To isolate high-risk entries missing upgrade plans: ```bash /ponytail-debt | grep no-trigger ``` ## Implementation Architecture The command integrates with the Ponytail extension through three key files: - **[`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md)** – Contains the grep logic, parsing rules, and output formatting instructions. - **[`commands/ponytail-debt.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml)** – Declares the user-facing description and prompt metadata. - **[`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js)** – Registers the command with the extension runtime at lines 64-66. ## Summary - **The /ponytail-debt command** scans repositories for `# ponytail:` and `// ponytail:` comments without modifying files. - It executes `grep -rnE '(#|//) ?ponytail:' .` while excluding `node_modules` and `.git`. - Each match generates a ledger row showing file, line, ceiling, and upgrade trigger. - Entries lacking upgrade paths are tagged `no-trigger` to highlight rot risk. - Output can be redirected to [`PONYTAIL-DEBT.md`](https://github.com/DietrichGebert/ponytail/blob/main/PONYTAIL-DEBT.md) for persistent tracking. ## Frequently Asked Questions ### What format must ponytail comments follow to be detected? Comments must follow the pattern `# ponytail: , ` or `// ponytail: , `. The command uses a regex that allows optional spacing after the comment delimiter to accommodate various style guides. ### Does /ponytail-debt modify my source files? No. The command is read-only and generates reports. It does not rewrite, delete, or alter any source files during execution. To persist results, you must redirect stdout to a file manually. ### How do I identify high-risk deferred shortcuts? Look for the `no-trigger` tag in the output. These entries indicate ponytail comments that specify a ceiling but omit an upgrade path, signaling debt that lacks a defined migration strategy and is likely to be forgotten. ### Where is the /ponytail-debt command registered in the extension? The command definition resides in [`commands/ponytail-debt.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml), while the runtime registration occurs in [`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) at lines 64-66. The skill implementation logic is documented in [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md).