What Does the ponytail-debt Skill Do? A Complete Guide to Tracking Technical Debt in Ponytail

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, the underlying command is:

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:

<file>:<line>, <description>. ceiling: <ceiling>. upgrade: <trigger>.

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:

/ponytail-debt

Typical output includes multiple ledger rows followed by a summary:

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:

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:

/ponytail-debt write PONYTAIL-DEBT.md

This command creates a 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:

// ponytail: 200 lines, replace with streaming parser

When processed, this generates:

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, which specifies the scanning command, output format, and operational boundaries. It is registered in the plugin manifest at .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. Human-readable command documentation is maintained in .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 while remaining read-only by default.
• Configuration resides in skills/ponytail-debt/SKILL.md with registration in .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, 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. The skill is registered for use in .qoder-plugin/plugin.json, with additional copies for OpenClaw at .openclaw/skills/ponytail-debt/SKILL.md and documentation at .opencode/command/ponytail-debt.md.

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