Skip to content

Make an empty description an error, with a list that only shrinks - #210

Closed
abernier wants to merge 1 commit into
llms-apis-fieldfrom
description-ratchet
Closed

Make an empty description an error, with a list that only shrinks#210
abernier wants to merge 1 commit into
llms-apis-fieldfrom
description-ratchet

Conversation

@abernier

Copy link
Copy Markdown
Member

An example with no description is still published: llms.txt carries it
as a directory name and a tag, and a model choosing between 170 of those
is choosing on a filename. Forty of them are in that state, which is
legal because the schema types the field as a bare string.

So the rule goes on at full strength -- empty is an error, and 120
characters is the bound -- and the examples that cannot pass it yet are
named in bin/description-exceptions.mjs. That is the shape
bin/e2e-exceptions.mjs already established here, 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 lists are the source of truth, and test/description-exceptions.test.ts
reads them the way the lint cannot -- backwards. The lint only asks
whether a failure was named, so on its own it would let an entry outlive
its reason forever. The test fails on a carved-out example that has since
been described, on a description that has since been emptied, and on a
recorded length that has drifted. Touching one of these descriptions
means updating the list in the same change.

The five over the bound get their own list rather than a truncation. Each
spends its overflow naming its stack in prose -- bubbles lists five
postprocessing effects -- which is the habit the new apis field exists
to absorb, so cutting at 120 would leave the same bad line, shorter.
They are rewrites, and this has to land before any description is
written.

schemas/pmndrs.schema.json keeps the bare string on purpose. minLength
and maxLength there would replay these 45 failures inside every editor
that opens one of these files -- red for known reasons again, in a venue
with no exception list to read. It tightens when the lists are empty,
which is also what closes #192.

Closes #195

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01YQmbpRu6oCNrLiUQvhz5x6


Stack created with GitHub Stacks CLIGive Feedback 💬

An example with no description is still published: `llms.txt` carries it
as a directory name and a tag, and a model choosing between 170 of those
is choosing on a filename. Forty of them are in that state, which is
legal because the schema types the field as a bare string.

So the rule goes on at full strength -- empty is an error, and 120
characters is the bound -- and the examples that cannot pass it yet are
named in `bin/description-exceptions.mjs`. That is the shape
`bin/e2e-exceptions.mjs` already established here, 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 lists are the source of truth, and `test/description-exceptions.test.ts`
reads them the way the lint cannot -- backwards. The lint only asks
whether a failure was named, so on its own it would let an entry outlive
its reason forever. The test fails on a carved-out example that has since
been described, on a description that has since been emptied, and on a
recorded length that has drifted. Touching one of these descriptions
means updating the list in the same change.

The five over the bound get their own list rather than a truncation. Each
spends its overflow naming its stack in prose -- `bubbles` lists five
postprocessing effects -- which is the habit the new `apis` field exists
to absorb, so cutting at 120 would leave the same bad line, shorter.
They are rewrites, and this has to land before any description is
written.

`schemas/pmndrs.schema.json` keeps the bare string on purpose. `minLength`
and `maxLength` there would replay these 45 failures inside every editor
that opens one of these files -- red for known reasons again, in a venue
with no exception list to read. It tightens when the lists are empty,
which is also what closes #192.

Closes #195

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YQmbpRu6oCNrLiUQvhz5x6
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make an empty description an error, with a list that only shrinks Distilled docs: one line to choose, an explainer once chosen

1 participant