# What Does the ponytail-debt Skill Do? A Complete Guide to Tracking Technical Debt in Ponytail > Discover the ponytail-debt skill and its role in tracking technical debt. This guide explains how it identifies postponed debt and classifies rot-risk within your repository. - Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) - Tags: how-to-guide - Published: 2026-08-29 --- **The ponytail-debt skill scans your entire repository for `ponytail:` comment markers and generates a deferred-shortcut ledger that surfaces postponed technical debt with automatic rot-risk classification.** The **ponytail-debt** skill is a built-in command within the DietrichGebert/ponytail repository designed to prevent "fix later" comments from vanishing into your codebase. It operates as a read-only audit tool that transforms inline deferral markers into a structured report, ensuring intentional shortcuts remain visible and actionable. ## How the ponytail-debt Skill Works The skill functions as a repository-wide scanner that detects special comment patterns and compiles them into a ledger format. ### Repository Scanning Mechanism When invoked, the skill executes a targeted grep command that walks the repository tree while excluding noise directories. According to the source specification in [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md), the underlying command is: ```bash grep -rnE '(#|//) ?ponytail:' . ``` This pattern matches both single-line comments starting with `// ponytail:` and hash-style comments starting with `# ponytail:`. The scan automatically skips `node_modules`, `.git`, and build artifacts to focus on source code. Each detected marker becomes one row in the ledger. The skill parses the comment content to extract three critical fields: - **Description** – The action item or context - **Ceiling** – The tolerance threshold (e.g., line count, latency) - **Upgrade** – The trigger condition for refactoring ### Ledger Output Format The skill formats each entry as: ```text :, . ceiling: . upgrade: . ``` If a comment lacks an explicit upgrade path, the row is tagged with `no-trigger` to highlight rot risk. After processing all matches, the skill reports the total number of markers and how many lack triggers, or prints *"No ponytail: debt. Clean ledger."* when none are found. ## Using the ponytail-debt Command The skill is exposed as a slash command in OpenClaw and Qoder environments. ### Running a Debt Report Invoke the skill with: ```text /ponytail-debt ``` Typical output includes multiple ledger rows followed by a summary: ```text src/utils.js:27, simplify array merge. ceiling: 50 lines. upgrade: replace with functional version. src/api/router.ts:104, shortcut DB call. ceiling: 30ms latency. upgrade: async version. ... 2 markers, 0 with no trigger. ``` When no debt markers exist: ```text No ponytail: debt. Clean ledger. ``` ### Persisting Results to Disk By default, the **ponytail-debt** skill operates in read-only mode and does not modify files. However, you can optionally persist the ledger to a markdown file: ```text /ponytail-debt write PONYTAIL-DEBT.md ``` This command creates a [`PONYTAIL-DEBT.md`](https://github.com/DietrichGebert/ponytail/blob/main/PONYTAIL-DEBT.md) file containing the same structured rows shown in the terminal output, suitable for version control or documentation. ## Comment Syntax and Detection For the skill to capture a deferral, developers must use the exact `ponytail:` prefix in comments. Here is a valid example from a JavaScript file: ```js // ponytail: 200 lines, replace with streaming parser ``` When processed, this generates: ```text src/parser.js:45, replace with streaming parser. ceiling: 200 lines. upgrade: replace with streaming parser. ``` The skill supports both `//` and `#` comment styles, making it compatible with JavaScript, TypeScript, Python, Ruby, and other languages. ## Integration and Registration The **ponytail-debt** skill is formally defined in [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md), which specifies the scanning command, output format, and operational boundaries. It is registered in the plugin manifest at [`.qoder-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.qoder-plugin/plugin.json), enabling invocation through the Qoder and OpenClaw platforms. For OpenClaw compatibility, a duplicate skill definition exists at [`.openclaw/skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/.openclaw/skills/ponytail-debt/SKILL.md). Human-readable command documentation is maintained in [`.opencode/command/ponytail-debt.md`](https://github.com/DietrichGebert/ponytail/blob/main/.opencode/command/ponytail-debt.md) and surfaced by the `ponytail-help` skill. ## Configuration and Boundaries The skill adheres to strict read-only semantics. It does not modify source code, delete comments, or alter file contents during execution. The grep-based approach ensures cross-platform compatibility without requiring language-specific parsers. The `no-trigger` tagging system serves as a risk indicator. Entries lacking upgrade paths represent potential technical rot, allowing teams to prioritize refactoring efforts based on the presence or absence of clear exit criteria. ## Summary - The **ponytail-debt** skill scans repositories for `ponytail:` comment markers using a grep-based approach that ignores dependency directories. - It generates a structured ledger showing file locations, descriptions, ceilings, and upgrade triggers, flagging entries without triggers as high-risk. - The skill is invoked via `/ponytail-debt` and can optionally write results to [`PONYTAIL-DEBT.md`](https://github.com/DietrichGebert/ponytail/blob/main/PONYTAIL-DEBT.md) while remaining read-only by default. - Configuration resides in [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md) with registration in [`.qoder-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.qoder-plugin/plugin.json). ## Frequently Asked Questions ### How do I add a debt marker that ponytail-debt will detect? Insert a comment starting with `ponytail:` followed by your description, ceiling, and upgrade plan. For example: `// ponytail: 100 lines, refactor to use streams`. The skill detects both `//` and `#` comment styles across all source files except those in `node_modules` or `.git`. ### Does ponytail-debt modify my source code? No. The skill is strictly read-only by design. It executes grep commands to scan files and only generates reports. You must explicitly request file persistence with the `write` argument to create [`PONYTAIL-DEBT.md`](https://github.com/DietrichGebert/ponytail/blob/main/PONYTAIL-DEBT.md), and even then, your original source files remain unchanged. ### What does the "no-trigger" tag mean in the output? The `no-trigger` tag appears when a `ponytail:` comment lacks a clear upgrade condition or refactoring trigger. This flags potential technical rot—deferred work with no defined exit criteria—helping teams identify which shortcuts need immediate attention to prevent future maintenance debt. ### Where is the ponytail-debt skill defined in the repository? The primary specification lives in [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md). The skill is registered for use in [`.qoder-plugin/plugin.json`](https://github.com/DietrichGebert/ponytail/blob/main/.qoder-plugin/plugin.json), with additional copies for OpenClaw at [`.openclaw/skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/.openclaw/skills/ponytail-debt/SKILL.md) and documentation at [`.opencode/command/ponytail-debt.md`](https://github.com/DietrichGebert/ponytail/blob/main/.opencode/command/ponytail-debt.md).