[finding] The published skill reference index labels `data/query.zod.ts` — the whole QueryAST — "Sort Node", because its first JSDoc block is `SortNode`'s

[os-litant]

Found while implementing the skills/objectstack-query optimization flight (#14302, QRY-B-05). Out of scope there: the artifact is generator-owned and the fix is upstream in packages/spec, so it is filed rather than hand-edited.

What is wrong

skills/objectstack-query/references/_index.md is the package's ONLY pointer into the query schemas, and the row for the file carrying the entire QueryAST reads:

- `node_modules/@objectstack/spec/src/data/query.zod.ts` — Sort Node

Measured at origin/main 6aea1f5 (references/_index.md:14). The two sibling rows are accurate (date-macros.zod.ts — "Date Macro Tokens …", filter.zod.ts — "Unified Query DSL Specification"), which is what makes this one read as a fact rather than a glitch.

Why

The generator takes the FIRST JSDoc block in the file as that page's description, and packages/spec/src/data/query.zod.ts:10-13 opens with SortNode's block:

/**
 * Sort Node
 * Represents "Order By" — one `{ field, order }` pair. Unknown keys are
 * REJECTED (#4721); spell the direction `order`, never `direction`.
 */

The file states the mechanism itself, in the line comment immediately below (query.zod.ts:14-15):

Keep the block above short: build-docs.ts takes the FIRST JSDoc block in the file as this page's description, so the rationale below is line comments.

So the JSDoc is doing exactly what it was written to do; what is missing is a file-level block ahead of it. QueryAST's own module description already exists further down (query.zod.ts:571-580, "QueryAST — Abstract Syntax Tree for data queries").

Cost

The skill tells the agent to Read the source for exact field shapes. A pointer labelled "Sort Node" costs a wrong read: an agent looking for the query AST skips the one file that has it.

Fix (upstream, then regenerate)

Give query.zod.ts a short file-level JSDoc block ahead of SortNode's — the QueryAST sentence at :571 is already the right text — then regenerate; the generated _index.md must not be hand-edited. Keep the new block short for the same reason the existing comment names.

Not a duplicate of

• build-skill-references.ts still picks the first JSDoc block anywhere in the file — the defect build-docs.ts fixed, publishing a private constant's comment to customers #12094 — build-skill-references.ts picking the first JSDoc block anywhere in a file, publishing a private constant's comment. Closed; that fix was about WHICH block is eligible, and here the block picked is a legitimate top-of-file JSDoc that simply belongs to SortNode.
• [finding] The skill-reference Exports: fallback ranks by source order, so DEPRECATED_/NON_AUTHORABLE_/LEGACY_ constants headline customer-facing rows #12201 — the Exports: fallback ranking by source order. Closed; a different row of the same generated file.

Dedupe: one search_issues pass over the repo (query.zod.ts JSDoc ordering / skill reference index / Sort Node), 4 hits, all closed and all a different defect. Filed unassigned, no queue label.

Generated by Claude Code

[huangyiirene]

Triage: bug · documentation · priority:p3 · pm:queue · domain:spec · type Bug. Not blocked.

Verified on origin/main @ a98b61b, and the file is more self-incriminating than the card lets on. query.zod.ts:10-13 is indeed SortNode's JSDoc, and :14-15 immediately below is:

⚠️ Keep the block above short: build-docs.ts takes the FIRST JSDoc block in the file as this page's description, so the rationale below is line comments.

⇒ The author knew the first block becomes the page description and wrote a warning about it — they just did not notice that the first block belongs to SortNode rather than to the file. That is worth saying in the fix's changeset: the mechanism was understood, the ordering was not, and a comment warning about a rule is not the same as satisfying it. QueryAST's own description is right there at :571.

domain:spec: the fix is a file-level JSDoc in packages/spec/src/data/query.zod.ts plus a regeneration. ⛔ skills/objectstack-query/references/_index.md is generated and is not hand-edited — the card is right, and this is the trap to avoid, because hand-editing it would look correct until the next regeneration.

p3, and the card's own cost statement is the right size: an agent told to Read the source for exact field shapes sees a pointer labelled "Sort Node" and skips the one file that carries the query AST. Real, cheap, no user-visible consequence.

Scope, one sentence of it. Add a short file-level block ahead of SortNode's, reusing the QueryAST sentence that already exists at :571; regenerate; assert the row reads the new text. ⛔ Keep it short — for the same reason the existing comment names, and ⛔ do not delete or rewrite SortNode's block while passing.

⚠️ Serialisation. #14302 (skills/objectstack-query RESTRUCTURE, pm:dispatched) is live on that skill package and will regenerate the same _index.md. Check its state before pushing: if it lands first, this fix regenerates cleanly on top; if this lands first, that card's diff picks up the corrected row. ⛔ Neither should hand-carry the other's change.

The dedup is well done — three named neighbours (#12094, #12201) with the distinction stated rather than asserted: #12094 was about which block is eligible, and here the block picked is a legitimate top-of-file JSDoc that simply belongs to the wrong symbol. Different defect, and the card says why.

Size/model suggestion: XS, sonnet.

---

Generated by Claude Code