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

New issue

Closed

opened 2026-07-21 15:32:51 +00:00 by crenshawdev · 1 comment

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).

john referenced this issue

2026-08-08 22:50:55 +00:00

minimalism: one lens at build, review and deferral, replacing #29/#30/#31 #95

john referenced this issue

2026-08-08 22:51:03 +00:00

review: over-engineering / minimalism lens (delete-list pass, separate from correctness) #29

john referenced this issue

2026-08-08 22:51:03 +00:00

executor: YAGNI-minimal output posture (build the minimum, flag the fuller option) #30

john commented

2026-08-08 22:51:04 +00:00

Owner

Superseded 2026-08-08 by #95, which folds this together with the other two into one requirement.

The three were one idea at three points in the lifecycle - don't build it (#30), catch it if built (#29), record it if deliberately deferred (#31) - and each is nearly worthless alone: a delete-list nobody acts on, a YAGNI default with no pass catching what slips through, a marker convention with no harvest. Filed separately they also read as three unaddressed proposals rather than one unmade decision, which is how the 2026 harness dossier scored them.

Nothing is dropped. The full text stays here; #95 carries the combined scope and the reason it is not v2.6.0.

Superseded 2026-08-08 by #95, which folds this together with the other two into one requirement. The three were one idea at three points in the lifecycle - don't build it (#30), catch it if built (#29), record it if deliberately deferred (#31) - and each is nearly worthless alone: a delete-list nobody acts on, a YAGNI default with no pass catching what slips through, a marker convention with no harvest. Filed separately they also read as three unaddressed proposals rather than one unmade decision, which is how the 2026 harness dossier scored them. Nothing is dropped. The full text stays here; #95 carries the combined scope and the reason it is not v2.6.0.

john closed this issue

2026-08-08 22:51:04 +00:00

john referenced this issue from a commit

2026-08-09 19:53:37 +00:00

docs: fold the minimalism cluster into one deferred requirement