Part of the distilled-docs spec (parent issue).
Why
40 of the 170 examples have an empty description. The JSON schema types it as a string with no minLength, which is how that is legal today. The other 130 have a median of 56 characters.
An example with no description and no tag exists in llms.txt as a directory name.
What
In bin/validate-pmndrs-metadata.mjs:
- a non-empty
description becomes an error
- length is bounded at 120 characters
- a written list of the 40 currently-empty examples is carved out, with a test that fails when the list and reality disagree
The pattern to follow
bin/e2e-exceptions.mjs already establishes this in the repo, down to its reasoning:
a suite that is red for known reasons is a suite nobody reads, and "known" has to mean written down
The list is the source of truth: [...] test/e2e-exceptions.test.ts fails if the two ever disagree.
an entry is a promise to come back to it
Same shape here. The list only shrinks. It reaching zero is what closes the parent spec.
Ordering
This must land after the schema PR (it edits the same file) and before any description is written. Turning the error on before the content exists would put CI red for 40 known reasons — which is the exact failure e2e-exceptions.mjs was written to prevent.
Done when
lint:metadata errors on a newly emptied description, the exception list holds exactly the 40, and its test fails if an entry is stale or missing.
How to implement
Start from a cleared session — this issue is written to be self-sufficient, and a session carrying the design discussion also carries the options that were rejected.
Branch off #194's branch (or main once it has merged) — both edit bin/validate-pmndrs-metadata.mjs, so they cannot run in parallel.
git checkout -b description-ratchet
/mattpocock-skills:implement #195
implement commits to the current branch, so the branch has to exist first — otherwise this lands on main.
Part of the distilled-docs spec (parent issue).
Why
40 of the 170 examples have an empty
description. The JSON schema types it as a string with nominLength, which is how that is legal today. The other 130 have a median of 56 characters.An example with no description and no tag exists in
llms.txtas a directory name.What
In
bin/validate-pmndrs-metadata.mjs:descriptionbecomes an errorThe pattern to follow
bin/e2e-exceptions.mjsalready establishes this in the repo, down to its reasoning:Same shape here. The list only shrinks. It reaching zero is what closes the parent spec.
Ordering
This must land after the schema PR (it edits the same file) and before any description is written. Turning the error on before the content exists would put CI red for 40 known reasons — which is the exact failure
e2e-exceptions.mjswas written to prevent.Done when
lint:metadataerrors on a newly emptied description, the exception list holds exactly the 40, and its test fails if an entry is stale or missing.How to implement
Start from a cleared session — this issue is written to be self-sufficient, and a session carrying the design discussion also carries the options that were rejected.
Branch off #194's branch (or
mainonce it has merged) — both editbin/validate-pmndrs-metadata.mjs, so they cannot run in parallel.implementcommits to the current branch, so the branch has to exist first — otherwise this lands onmain.