Lint zorch docs

Skill fractalyze/zorch/.claude/skills/lint-zorch-docs

zorch-specific documentation review. `tools/lint_docs.py` runs as a pre-commit hook and settles the two questions the filesystem answers — whether a cited symbol resolves, and whether a relative link does. This skill covers everything else, all of which needs reading: subsystem page coverage, whether a page answers why-this-shape, fusion-by-construction and where it sits in the composition vocabulary; whether CLAUDE.md has stayed a pointer; and whether a scheme or zkVM is named as anything but the consumer boundary. Wraps /workflow:lint-docs for the universal checks. TRIGGER when: (1) /lint-zorch-docs, (2) after touching CLAUDE.md / README.md / docs/, (3) after adding a new subsystem, (4) before a docs PR. SKIP when: outside the zorch repo; the universal pass already ran clean and only zorch-specific scope changed.From its SKILL.md

Install

npx -y skills add fractalyze/zorch --skill lint-zorch-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

12 stars12 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.6 KB, as published. Nobody here has run it

Lint zorch Docs

The mechanical half is not here. tools/lint_docs.py settles whether a cited symbol or link resolves, because a rule written as prose drifts silently while a rule that runs fails the commit that breaks it — this file previously named commit/jagged as the one nested block earning its own page, a path that never existed. Nothing below restates a tree fact.

It deliberately stops at resolution. Whether every subsystem has a page, whether a claim is stated once, whether a module is reachable from the docs at all — all real, none decidable from the filesystem without encoding an editorial rule as CI. They are checks J1-J3 below, read rather than run.

Three stages:

python3 tools/lint_docs.py — reference resolution. Fix what it reports first; the judgment checks read a moving target otherwise.
/workflow:lint-docs — universal prose checks. Surface its report.
J1–J3 below, merged into the same report.

The conventions these enforce live in docs/reference/conventions.md (the subsystem doc skeleton and the WHY-not-WHAT rule) and the two non-negotiables in CLAUDE.md / README.md. When a rule drifts, fix the convention doc and re-run.

Bail-out

If $(basename $(git rev-parse --show-toplevel)) does not start with zorch, stop and point the user at /workflow:lint-docs.

Checks

J1. Subsystem coverage and skeleton (High)

Every subsystem under zorch/ should have a page under docs/, linked from the hub, and every top-level module should be reachable from some page — the lint no longer checks either, so check them here.

Every block page must answer the three things conventions.md mandates: why this shape (the concept it factors, and how it stays proving-scheme- and implementation-agnostic), fusion by construction, and where it sits in the composition vocabulary (which components are stage roles, which are rounds, the claim each role reduces and to what).

Headings are a hint, not the test — coding.md covers the first two under different titles and is conventions-blessed. Read for the ideas. A block with no stage role passes the third by saying so; silence does not.

J2. CLAUDE.md shape (Medium)

zorch's CLAUDE.md is a pointer to README.md and docs/, plus exactly two content sections: Two non-negotiables and Development environment. Flag any other content section. The non-negotiables must agree with README.md's Design Philosophy — but agreement by linking the same canonical statement, not by carrying a second copy of it, which is how the fusion claim drifted into contradiction with what the north star measured.

J3. Agnostic naming (Low)

A zkVM name (sp1, openvm, zisk, risc0, jolt) or a consumer repository may appear only as the consumer boundary ("lives in the consumer", "adapted from …"). Generic scheme names (FRI, Basefold, WHIR, STARK, GKR, sumcheck) are fine anywhere. Flag a mention that reads as a zorch dependency or feature.

Procedure

Bail-out check.
Run the three stages above.

Merge into one report:

# /lint-zorch-docs report

## Reference resolution (tools/lint_docs.py)
...

## Universal (from /workflow:lint-docs)
...

## zorch-specific judgment
### High / Medium / Low
- J<n> — <finding>. Suggested fix: <action>.

## Summary
<combined counts; --fix pointer if applicable>

With --fix: defer mechanical fixes to tools/lint_docs.py's own messages and to the upstream skill. For a J1 gap, offer to draft the missing section from the nearest worked shape — but put the WHY prose up for review, never invent it. Prompt per finding via AskUserQuestion; the rest report-only.