capture: in-code deliberate-shortcut marker harvested into a debt ledger #31

New issue

Open

opened 2026-07-21 15:32:51 +00:00 by crenshawdev · 0 comments

crenshawdev commented

2026-07-21 15:32:51 +00:00

(Migrated from github.com)

Summary

A lightweight convention for marking an intentional corner-cut at the point in the code where it is cut, naming its ceiling and its upgrade trigger, then grep-harvesting all such markers into a ledger. Feeds the same deferred-work stream cad-capture already owns.

Motivation

cad-executor records deviations in the phase SUMMARY, but a deliberate shortcut (a global lock, an O(n^2) scan, a naive heuristic) has no home at its location in the code. So "later" rots into "never" with no trigger to revisit and no pointer from the code back to the deferral. An in-code marker with a named ceiling and upgrade path is greppable and survives independent of the plan docs.

Prior art

ponytail's marker convention plus its ponytail-debt skill (https://github.com/DietrichGebert/ponytail). Convention: a comment ponytail: <ceiling>, <upgrade trigger> at the cut. The debt skill greps them into a ledger, one row per marker grouped by file, and flags any marker with no upgrade trigger as no-trigger, which are precisely the ones that silently rot.

Notes

This overlaps cad-capture and the (now dropped from the repo) CAPTURE.md stream. It is a refinement, in-code and greppable, not a new tracker. Decide whether the ledger is capture output or a separate debt file.
Pick a cadence-native marker token, not ponytail:.

Acceptance (rough)

A documented in-code marker convention: token, ceiling, upgrade trigger.
A harvest step (grep) that lists markers grouped by file and flags trigger-less ones.
A decision on where the ledger lives relative to capture.

Part of a three-issue set seeded from the ponytail survey (over-engineering review lens, and the executor minimalism posture).

## Summary A lightweight convention for marking an intentional corner-cut at the point in the code where it is cut, naming its ceiling and its upgrade trigger, then grep-harvesting all such markers into a ledger. Feeds the same deferred-work stream cad-capture already owns. ## Motivation `cad-executor` records deviations in the phase SUMMARY, but a deliberate shortcut (a global lock, an O(n^2) scan, a naive heuristic) has no home *at its location in the code*. So "later" rots into "never" with no trigger to revisit and no pointer from the code back to the deferral. An in-code marker with a named ceiling and upgrade path is greppable and survives independent of the plan docs. ## Prior art ponytail's marker convention plus its `ponytail-debt` skill (https://github.com/DietrichGebert/ponytail). Convention: a comment `ponytail: <ceiling>, <upgrade trigger>` at the cut. The debt skill greps them into a ledger, one row per marker grouped by file, and flags any marker with no upgrade trigger as `no-trigger`, which are precisely the ones that silently rot. ## Notes - This overlaps cad-capture and the (now dropped from the repo) CAPTURE.md stream. It is a refinement, in-code and greppable, not a new tracker. Decide whether the ledger *is* capture output or a separate debt file. - Pick a cadence-native marker token, not `ponytail:`. ## Acceptance (rough) - [ ] A documented in-code marker convention: token, ceiling, upgrade trigger. - [ ] A harvest step (grep) that lists markers grouped by file and flags trigger-less ones. - [ ] A decision on where the ledger lives relative to capture. Part of a three-issue set seeded from the ponytail survey (over-engineering review lens, and the executor minimalism posture).