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

New issue

Closed

opened 2026-08-08 22:50:55 +00:00 by john · 1 comment

john commented

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

Owner

The one idea

Over-building is not a bug. It is code that works and should not exist, which is precisely why an adversarial correctness review cannot catch it - nothing it checks is wrong. Cadence names this failure mode nowhere today. The three points where it can be attacked, cheapest first:

Build time (was #30). cad-executor ships the lean version and flags the fuller option in one line of the deviation record, instead of building it speculatively. Cheapest, because nothing is created that later has to be found and deleted.
Review time (was #29). A pass that hunts complexity to delete - reinvented stdlib, single-implementation abstractions, dead flexibility, config nobody sets - returning a ranked delete-list and applying nothing. Distinct from the correctness reviewer, and separate from it on purpose.
Deferral time (was #31). A deliberate corner-cut gets a greppable marker at its location in the code naming its ceiling and its upgrade trigger, harvested into a ledger that feeds the same deferred-work stream /cad-capture already owns. Without it, "later" rots into "never" with no pointer from the code back to the deferral.

Why one requirement rather than three issues

Each part is guidance or a lens, not a subsystem, and each is nearly worthless alone: a delete-list nobody acts on, a YAGNI default with no pass that catches what slips through it, a marker convention with no harvest. Together they are a single stated posture with one place to argue about it.

The 2026 harness dossier audited Cadence at v2.4.0, ranked it #1 of 35, and listed "strengthen minimalism/debt capture proposals" as improvement priority #4 - reading exactly these three open issues and scoring them as outstanding.

Scope note

Not v2.6.0. That cycle is the reconciliation cycle (queue triage, live friction, parser defects, doc sweep) and its byte budgets are already tight - every prose surface the live-friction phase touches sits at exactly its budget today. Parts 1 and 2 ADD resident prose, which is the same objection that deferred CTX-02 out of v2.5.0. This lands as one requirement in a later cycle, planned as a whole.

Prior art

ponytail (https://github.com/DietrichGebert/ponytail): ponytail-review and ponytail-audit are the delete-list pass, one line per finding tagged delete / stdlib / native / yagni / shrink, ranked biggest-cut-first, ending in net: -N lines possible, applying nothing. Its ladder - does this need to exist, reuse what is here, stdlib, native, installed dep, one line, then build - is the build-time posture. Worth lifting the lens, not the code.

Supersedes #29 (review minimalism lens), #30 (executor YAGNI posture) and #31 (in-code shortcut marker harvested to a debt ledger). Those three are one idea observed at three points in the lifecycle, and filing them separately made the spine look like it had three unaddressed proposals rather than one unmade decision. ## The one idea Over-building is not a bug. It is code that works and should not exist, which is precisely why an adversarial *correctness* review cannot catch it - nothing it checks is wrong. Cadence names this failure mode nowhere today. The three points where it can be attacked, cheapest first: 1. **Build time (was #30).** `cad-executor` ships the lean version and flags the fuller option in one line of the deviation record, instead of building it speculatively. Cheapest, because nothing is created that later has to be found and deleted. 2. **Review time (was #29).** A pass that hunts complexity to *delete* - reinvented stdlib, single-implementation abstractions, dead flexibility, config nobody sets - returning a ranked delete-list and applying nothing. Distinct from the correctness reviewer, and separate from it on purpose. 3. **Deferral time (was #31).** A deliberate corner-cut gets a greppable marker at its location in the code naming its ceiling and its upgrade trigger, harvested into a ledger that feeds the same deferred-work stream `/cad-capture` already owns. Without it, "later" rots into "never" with no pointer from the code back to the deferral. ## Why one requirement rather than three issues Each part is guidance or a lens, not a subsystem, and each is nearly worthless alone: a delete-list nobody acts on, a YAGNI default with no pass that catches what slips through it, a marker convention with no harvest. Together they are a single stated posture with one place to argue about it. The 2026 harness dossier audited Cadence at v2.4.0, ranked it #1 of 35, and listed "strengthen minimalism/debt capture proposals" as improvement priority #4 - reading exactly these three open issues and scoring them as outstanding. ## Scope note Not v2.6.0. That cycle is the reconciliation cycle (queue triage, live friction, parser defects, doc sweep) and its byte budgets are already tight - every prose surface the live-friction phase touches sits at exactly its budget today. Parts 1 and 2 ADD resident prose, which is the same objection that deferred CTX-02 out of v2.5.0. This lands as one requirement in a later cycle, planned as a whole. ## Prior art ponytail (https://github.com/DietrichGebert/ponytail): `ponytail-review` and `ponytail-audit` are the delete-list pass, one line per finding tagged delete / stdlib / native / yagni / shrink, ranked biggest-cut-first, ending in `net: -N lines possible`, applying nothing. Its ladder - does this need to exist, reuse what is here, stdlib, native, installed dep, one line, then build - is the build-time posture. Worth lifting the lens, not the code.

john added the

enhancement

label

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

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 referenced this issue

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

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

john commented

2026-08-09 01:10:06 +00:00

Author

Owner

Split 2026-08-08. Part 3 - the in-code shortcut marker and its harvest - is pulled forward into v2.6.0 phase 3 (Field friction) as requirement DBT-01. Parts 1 and 2, the executor's YAGNI posture and the review delete-list, stay deferred here under MIN-01 with their existing reasoning unchanged.

The split is not arbitrary. The objection that defers parts 1 and 2 is that they add resident prose on the dispatch path, in a cycle whose surfaces already sit at exactly their byte budgets. That objection does not reach part 3: a comment convention plus a harvest seam adds nothing to what any agent carries per dispatch. This is a foothold, not the posture change.

Two measurements taken before writing the requirement, both of which constrain it:

The tree already carries 19 conventional markers - 14 TODO, 2 NOTE, 1 each XXX, HACK, FIXME - and nothing lints any of them. A harvest keyed on TODO would return 19 false positives on its first run, so the convention needs its own token and the phase criterion says so explicitly.

.planning/CAPTURE.md's tracked state varies by project: gitignored in this repo and in burnrate, tracked in hindsight and assistant. That asymmetry needed a stated answer rather than an assumption, and the requirement takes the coherent one - the marker in tracked code is the durable record, the queue is a regenerable view of it, and the harvest is therefore idempotent. A queue lost to a clone is rebuilt by re-running the harvest. That is also why the harvest is a seam carrying its CONTRACTS row rather than a documented grep: only a seam can be idempotent and carry the regression test that proves it finds a planted marker and does not invent one.

This issue stays open for parts 1 and 2.

Split 2026-08-08. **Part 3 - the in-code shortcut marker and its harvest - is pulled forward into `v2.6.0` phase 3 (Field friction) as requirement `DBT-01`.** Parts 1 and 2, the executor's YAGNI posture and the review delete-list, stay deferred here under `MIN-01` with their existing reasoning unchanged. The split is not arbitrary. The objection that defers parts 1 and 2 is that they add resident prose on the dispatch path, in a cycle whose surfaces already sit at exactly their byte budgets. That objection does not reach part 3: a comment convention plus a harvest seam adds nothing to what any agent carries per dispatch. This is a foothold, not the posture change. Two measurements taken before writing the requirement, both of which constrain it: **The tree already carries 19 conventional markers** - 14 `TODO`, 2 `NOTE`, 1 each `XXX`, `HACK`, `FIXME` - and nothing lints any of them. A harvest keyed on `TODO` would return 19 false positives on its first run, so the convention needs its own token and the phase criterion says so explicitly. **`.planning/CAPTURE.md`'s tracked state varies by project**: gitignored in this repo and in `burnrate`, tracked in `hindsight` and `assistant`. That asymmetry needed a stated answer rather than an assumption, and the requirement takes the coherent one - the marker in tracked code is the durable record, the queue is a regenerable view of it, and the harvest is therefore idempotent. A queue lost to a clone is rebuilt by re-running the harvest. That is also why the harvest is a seam carrying its `CONTRACTS` row rather than a documented grep: only a seam can be idempotent and carry the regression test that proves it finds a planted marker and does not invent one. This issue stays open for parts 1 and 2.

john referenced this issue from a commit

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

docs: fold the minimalism cluster into one deferred requirement

john referenced this issue from a commit

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

docs: pull the shortcut-marker half of MIN-01 forward as DBT-01 in phase 3

john added this to the v3.1.0 milestone

2026-08-12 16:37:08 +00:00

john closed this issue

2026-08-13 15:32:17 +00:00