green-pt/honey-for-devs/honey-debt

Honey Debt

Lever 1 trades code for a known ceiling. That trade is only honest if someone can see it later. Every deliberate simplification carries a shortcut: comment naming its ceiling and the trigger to revisit; this collects them into one ledger. Older code may carry the previous honey: prefix — same convention, harvest both.

Scan

P='(#|//|--|/\*) ?(shortcut|honey):'
if git rev-parse --git-dir >/dev/null 2>&1; then git grep --untracked -nE "$P"
else grep -rnE "$P" . --exclude-dir={node_modules,.git,dist,build,vendor}; fi

Each hit is one row. git grep skips everything gitignored. The comment prefix is what 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>. trigger: <when to revisit>.

The convention is shortcut: <ceiling>, <trigger>, so both fields come straight from the comment. Add git blame -L<line>,<line> -- <file> per row only if the user asks who owns it.

Tag any marker with no trigger no-trigger — a ceiling without a revisit condition is the shape that rots. End with:

<N> markers, <M> with no trigger.

Nothing found: No shortcut debt. Clean ledger.

Boundaries

• Report only. Don't fix, refactor, or remove markers — the user decides what to

pay down. Offer, don't act.

• Don't invent debt. A TODO/FIXME is not a shortcut: marker; mention the count

separately at most once if it's large, don't fold it into the ledger.

• Don't editorialise per row. The ledger is data. Save any judgement for one

closing line, and only if something is genuinely alarming.