Origin
Finding from the AX-guide (llms.txt) quality audit workflow (AXGuideAudit-tenferro-rs, run 32342177234), which evaluates the published llms.txt from the perspective of a cold-start coding agent. Report reviewed and approved by a human before filing (per the audit's safety policy). Proposed in shinaoka/task-management-terasaki#31.
Audit verdicts
| Check |
Verdict |
| One-fetch minimal working examples (svd / qr / einsum / matmul / grad) |
PASS (all five) |
| Trap phrased as warning: column-major storage |
PASS |
| Trap phrased as warning: einsum dialect restrictions |
FAIL |
| Trap phrased as warning: backend/runtime reuse |
PASS |
| Inline conventions in llms.txt body |
PASS |
The failure
The einsum dialect restrictions are presented as a neutral specification summary, while the other two traps name their failure mode and consequence. llms.txt ("Conventions you must know before writing code"):
Einsum dialect. Equations need the explicit arrow ("ij,jk->ik"). Flat notation supports one right-aligned, broadcastable ... ellipsis per term; EinsumNotation is the programmatic form. Parenthesized ellipsis remains unsupported.
skill-references/pitfalls.md similarly says "Use the explicit arrow in every equation" and "Parenthesized ellipsis remains unsupported", and the Einsum guide describes the supported dialect without warning language.
None of these states what happens when the rule is violated (omitted arrow, parenthesized ellipsis): is it rejected at parse time, a runtime error, or silently wrong results? Compare the column-major entry, which names both the failure mode and the consequence ("silently reinterpreted … permuted/wrong values, never rejected"), and the backend entry ("per-call construction discards the buffer pool").
Impact on cold-start agents
An agent reading only llms.txt (or the Pitfalls page) can treat the arrow requirement and the ellipsis restriction as stylistic conventions rather than correctness constraints, and has no basis to predict the failure it will hit — which matters most if any violation fails silently or with a misleading error (cf. #1131, where misparsed ellipsis produced a misleading error).
Suggested remediation
Rephrase the einsum entries as explicit warnings that name the actual, verified failure mode and consequence, in the same shape as the column-major and backend-reuse entries:
docs/llms.txt — the "Einsum dialect" convention line: append the consequence of omitting the arrow and of parenthesized ellipsis (e.g. "rejected with error E at parse time", or the actual behavior).docs/skill-references/pitfalls.md — Einsum syntax section: same change.docs/guides/einsum.html source — add the same warning where the dialect is introduced.
Please document the behavior the implementation actually has (parse-time rejection vs runtime error vs silent misbehavior), rather than a guessed one.
Mechanical CI status at audit time
Documentation-related CI on main was green: "Deploy Documentation" and "CI PR workspace tests" both succeeded (2026-08-19). No open PR addresses this finding; closed #1641 / #1613 / #1661 established the current llms.txt but do not cover warning-shaped phrasing for the einsum dialect.
🤖 Generated with Claude Code
Origin
Finding from the AX-guide (llms.txt) quality audit workflow (
AXGuideAudit-tenferro-rs, run 32342177234), which evaluates the publishedllms.txtfrom the perspective of a cold-start coding agent. Report reviewed and approved by a human before filing (per the audit's safety policy). Proposed in shinaoka/task-management-terasaki#31.4a15a13214e3e851bb8f53e667246d50efbcc435(main)Audit verdicts
The failure
The einsum dialect restrictions are presented as a neutral specification summary, while the other two traps name their failure mode and consequence.
llms.txt("Conventions you must know before writing code"):skill-references/pitfalls.md similarly says "Use the explicit arrow in every equation" and "Parenthesized ellipsis remains unsupported", and the Einsum guide describes the supported dialect without warning language.
None of these states what happens when the rule is violated (omitted arrow, parenthesized ellipsis): is it rejected at parse time, a runtime error, or silently wrong results? Compare the column-major entry, which names both the failure mode and the consequence ("silently reinterpreted … permuted/wrong values, never rejected"), and the backend entry ("per-call construction discards the buffer pool").
Impact on cold-start agents
An agent reading only
llms.txt(or the Pitfalls page) can treat the arrow requirement and the ellipsis restriction as stylistic conventions rather than correctness constraints, and has no basis to predict the failure it will hit — which matters most if any violation fails silently or with a misleading error (cf. #1131, where misparsed ellipsis produced a misleading error).Suggested remediation
Rephrase the einsum entries as explicit warnings that name the actual, verified failure mode and consequence, in the same shape as the column-major and backend-reuse entries:
docs/llms.txt— the "Einsum dialect" convention line: append the consequence of omitting the arrow and of parenthesized ellipsis (e.g. "rejected with error E at parse time", or the actual behavior).docs/skill-references/pitfalls.md— Einsum syntax section: same change.docs/guides/einsum.htmlsource — add the same warning where the dialect is introduced.Please document the behavior the implementation actually has (parse-time rejection vs runtime error vs silent misbehavior), rather than a guessed one.
Mechanical CI status at audit time
Documentation-related CI on main was green: "Deploy Documentation" and "CI PR workspace tests" both succeeded (2026-08-19). No open PR addresses this finding; closed #1641 / #1613 / #1661 established the current llms.txt but do not cover warning-shaped phrasing for the einsum dialect.
🤖 Generated with Claude Code