ponytail-debt: use native documentation conventions and offer external tracking #1123

I like that Ponytail makes deliberate shortcuts explicit: the limit and the condition for revisiting it should survive the coding session. Could that fit the project's native documentation conventions, with an option to track the follow-up in its existing issue tracker?

The current split makes sense: the main skill writes shortcut: comments, while /ponytail-debt reads them into a ledger and can persist that ledger to a file on request.

Native documentation conventions

When a limitation belongs in a declaration's documentation, use the project's existing JSDoc, TSDoc, Javadoc, docstring, or equivalent convention. Extend the existing documentation rather than adding a separate comment solely for Ponytail. Local implementation details can still use ordinary inline comments.

Keep the useful content: what was simplified, its known limit, and when to revisit it. Use the format's supported prose/tags rather than inventing a universal @debt tag. For example, a JSDoc-style block could contain:

/**
 * Looks up a cached result.
 *
 * shortcut: process-local cache, use shared storage when workers must share state.
 */

The scanner needs to recognize this placement too. I checked the exact git grep command in the debt skill at 2961b52: it finds an equivalent // shortcut: line but misses the * shortcut: continuation line above. #1076 raised continuation lines; the narrower open #1117 covers other comment prefixes.

Optional external tracking

After presenting the ledger, offer to create or update selected items in GitHub Issues, Jira, or whichever tracker the project already uses. Use the host agent's available tools; a tracker-specific integration is not necessary for this proposal.

• Keep reporting read-only by default; creating or updating tickets is opt-in.
• Carry over the source location, known limit, and revisit trigger, and reuse an existing ticket when one is already linked.
• Honor project guidance about keeping debt in comments, the tracker, or both. Where both are used, link the ticket from the comment instead of maintaining two separate descriptions.
• If no tracker tool is available, offer a ready-to-file description.

Existing decisions

I read #120, #887, and #1068, along with the README's marker FAQ. The neutral marker, custom marker word, and project-level override already address part of this. This proposal keeps the opinionated default and focuses on native documentation and an optional external follow-up workflow.

A small starting point could be examples in the docs and guidance in the debt skill. Any ruleset implementation would need the benchmarks required by CONTRIBUTING.