ponytail-debt

dietrichgebert/ponytail

Harvest ponytail: comments into a debt ledger to track deliberate shortcuts before they rot.

What is ponytail-debt?

Scans the codebase for `ponytail:` comment markers that document deliberate shortcuts and deferrals, collecting them into a single ledger report. Use when you need visibility into what was intentionally deferred and why, so technical debt doesn't silently become permanent.

Grep the repo for all `ponytail:` comment markers, skipping node_modules, .git, and build output
Group findings by file with line numbers, what was simplified, ceiling, and upgrade trigger
Flag rot-risk markers that have no upgrade path or trigger defined
Optionally write the ledger to a file like PONYTAIL-DEBT.md for persistence
Read-only operation; changes nothing in the codebase

How to install ponytail-debt

npx skills add https://github.com/dietrichgebert/ponytail --skill ponytail-debt

Claude Code

Cursor

Windsurf

Cline

How to use ponytail-debt

1.Trigger the skill by saying 'ponytail debt', '/ponytail-debt', 'what did ponytail defer', 'list the shortcuts', 'ponytail ledger', or 'what did we mark to do later'
2.The skill scans the repo and outputs a ledger with one row per marker, grouped by file
3.Review the output for markers flagged with 'no-trigger' as rot risks
4.Optionally ask the skill to write the ledger to a file for persistence
5.Say 'stop ponytail-debt' or 'normal mode' to exit the skill

Use cases

Good for

Review what shortcuts were taken during rapid development and when to revisit them
Identify deferred work that lacks a clear trigger, so it doesn't disappear from view
Generate a debt ledger before a refactor or upgrade cycle to prioritize what to address
Track ceiling limits on simplified code so you know when complexity has grown too far
Audit which team members marked deferrals using git blame integration

Who it's for

Development teams managing technical debt
Code reviewers assessing shortcut impact
Project leads planning refactor or upgrade cycles
Developers inheriting codebases with deliberate shortcuts

ponytail-debt FAQ

What format should ponytail comments follow?

The convention is `ponytail: <ceiling>, <upgrade path>`. The comment prefix (# or //) is stripped, and the ceiling and trigger are extracted directly from the comment text.

What happens if a ponytail comment has no upgrade path?

It gets flagged with a 'no-trigger' tag, indicating a rot risk—a deferral that could silently become permanent without a clear trigger to revisit it.

Does this skill modify my code?

No. It reads and reports only. Changes nothing in the codebase. You can optionally ask it to write the ledger to a file for persistence.

Can I see who marked each shortcut?

Yes. The skill can add `git blame` output per row to show the owner of each ponytail comment.

What if no ponytail comments are found?

The skill outputs 'No ponytail: debt. Clean ledger.'

Full instructions (SKILL.md)

Source of truth, from dietrichgebert/ponytail.

name: ponytail-debt description: > Harvest every `ponytail:` comment in the codebase into a debt ledger, so the deliberate shortcuts and deferrals ponytail leaves behind get tracked instead of rotting into "later means never". Use when the user says "ponytail debt", "/ponytail-debt", "what did ponytail defer", "list the shortcuts", "ponytail ledger", or "what did we mark to do later". One-shot report, changes nothing.

Every deliberate ponytail shortcut is marked with a ponytail: comment naming its ceiling and upgrade path. This collects them into one ledger so a deferral can't quietly become permanent.

Scan

Grep the repo for comment markers, skipping node_modules, .git, and build output:

grep -rnE '(#|//) ?ponytail:' . (add other comment prefixes if your stack uses them)

Each hit is one ledger row. The comment prefix keeps prose that merely mentions the convention out of the ledger.

Output

One row per marker, grouped by file:

<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.

The convention is ponytail: <ceiling>, <upgrade path>, so pull the ceiling and the trigger straight from the comment. Want an owner per row too? add git blame -L<line>,<line>.

Flag the rot risk: any ponytail: comment that names no upgrade path or trigger gets a no-trigger tag, those are the ones that silently rot.

End with <N> markers, <M> with no trigger. Nothing found: No ponytail: debt. Clean ledger.

Boundaries

Reads and reports only, changes nothing. To persist it, ask and it writes the ledger to a file (e.g. PONYTAIL-DEBT.md). One-shot. "stop ponytail-debt" or "normal mode" to revert.