ponytail-debt

DietrichGebert ｜ 架構與重構 ｜ 原文 ｜ MIT

把所有 shortcut 註解列成技術債帳本，標出沒寫升級條件的

---
name: ponytail-debt
description: >
  把每一則 `shortcut:` 註解（以及較舊的 `ponytail:`）列成技術債帳本。一次性報告，
  不改任何東西。用於「ponytail debt」、「what did ponytail defer」、「list the
  shortcuts」、/ponytail-debt。
---

每個刻意的 ponytail 捷徑，都會用一則 `shortcut:` 註解標出它的上限和升級路徑
（較舊的程式碼可能寫 `ponytail:`）。這個 skill 把它們集中成一份帳本，讓延後處理的事
不會悄悄變成永久的。

## 掃描

在 repo 裡 grep 註解標記，跳過 `.git` 和所有被
`.gitignore` 忽略的東西（相依套件、build 輸出、快取，不管哪種技術堆疊）：

`git grep --no-index --exclude-standard -nE '(#|//|/[*]) ?(shortcut|ponytail):'`  （如果你的技術堆疊用其他的註解前綴，就加上去）

如果使用者指定了自己的標記字（`/ponytail-debt TODO`），就改 grep 那個字。

每個命中是帳本的一列。註解前綴能讓只是提到這個慣例的
文字不被放進帳本。要跳過不是延後處理的命中，例如
講鍵盤快捷鍵（keyboard shortcut）的註解。

## 輸出

每個標記一列，依檔案分組：

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

慣例是 `shortcut: <ceiling>, <upgrade path>`，所以直接從註解裡取出上限
和觸發條件。想要每列也附上負責人？加上
`git blame -L<line>,<line>`。

標出會腐爛的風險：任何沒寫升級路徑或
觸發條件的標記註解，都加上 `no-trigger` 標籤，那些就是會悄悄腐爛的。

結尾寫 `<N> markers, <M> with no trigger.` 什麼都沒找到：寫 `No shortcut debt. Clean ledger.`

## 範圍界線

只讀取並回報，不改任何東西。想存下來的話，跟它說一聲，它會把
帳本寫進檔案（例如 `PONYTAIL-DEBT.md`）。一次性。

---
name: ponytail-debt
description: >
  List every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report,
  changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the
  shortcuts", /ponytail-debt.
---

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

## Scan

Grep the repo for comment markers, skipping `.git` and everything the
`.gitignore` files ignore (dependencies, build output, caches, in any stack):

`git grep --no-index --exclude-standard -nE '(#|//|/[*]) ?(shortcut|ponytail):'`  (add other comment prefixes if your stack uses them)

If the user names their own marker word (`/ponytail-debt TODO`), grep for that word instead.

Each hit is one ledger row. The comment prefix keeps prose that merely mentions
the convention out of the ledger. Skip hits that are not a deferral, like a note
about a keyboard shortcut.

## 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 `shortcut: <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 marker 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 shortcut 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.