docs-rules-check
Review documents under docs/ and the Lorecraft specs in docs/__meta__/ that govern them - run lorecraft check for frontmatter, section outline, word caps and token budget, walk each spec's checklist for what a machine cannot decide, and check that each changed spec loads, that its prose and JSON agree, and that it governs the documents intended. Use after editing anything under docs/, when reviewing a pull request that touches docs/, before committing, when lorecraft check exits 1 or 2, or a document is unexpectedly ungoverned, or when setting the checks up in CI. Not for writing documents or specs; see /docs-rules and /docs-rules-creator
- License 许可
- Apache-2.0
- 所属仓库
- LNSD/lorecraft
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- docs-rules-check
- description
- Review documents under docs/ and the Lorecraft specs in docs/__meta__/ that govern them - run lorecraft check for frontmatter, section outline, word caps and token budget, walk each spec's checklist for what a machine cannot decide, and check that each changed spec loads, that its prose and JSON agree, and that it governs the documents intended. Use after editing anything under docs/, when reviewing a pull request that touches docs/, before committing, when lorecraft check exits 1 or 2, or a document is unexpectedly ungoverned, or when setting the checks up in CI. Not for writing documents or specs; see /docs-rules and /docs-rules-creator
- allowed-tools
- Bash(lorecraft check*) Bash(lorecraft inspect*) Bash(uvx lorecraft *) Bash(uv run lorecraft *) Bash(git diff *) Bash(git status *) Bash(git merge-base *) Bash(grep *) Bash(ls docs/*)
- compatibility
- Requires the lorecraft command, on PATH or run through uvx lorecraft, or uv run lorecraft in a uv project that declares Lorecraft as a dependency, and a git checkout
03 SKILL.md 正文
Docs Rules Check
The review pass over docs/. For a changed document it verifies that the document follows the specs
in docs/__meta__/ that govern it; for a changed spec, that it loads, agrees with itself, and governs
what it claims to. This is a conformance check, not a review of content: it does not question whether a
convention is the right one, or whether the code a document describes works.
This skill carries no per-corpus conventions. It resolves the specs from each document's path and validates
against them. It reports; the fixes belong to the writing paths — /docs-rules for a document,
/docs-rules-creator for a spec.
Running lorecraft
Every command below calls lorecraft directly. Where it is not on PATH, run uvx lorecraft … instead, or
uv run lorecraft … in a uv project that declares Lorecraft as a dependency. Run from the repository root.
1. The changeset
git status --short -- docs # uncommitted work, the default
git diff --name-only "$(git merge-base HEAD main)"...HEAD -- docs # a whole branch
Given explicit paths, check those instead. Split what changed in two:
- Documents — every changed Markdown file outside
docs/__meta__/. §2 to §5 check them. - Specs — every changed file in
docs/__meta__/. A change to any file at a spec name is a change to that spec: its prose and every JSON file beside it. §6 checks them.
2. The specs that govern each document
lorecraft inspect
Each document is followed by the names of the specs governing it, broad to narrow; the name <name> is the
prose at docs/__meta__/<name>.md.
cli-inspect describes the output. Read every
spec listed for a document before the document, so its checklist is in hand while reading. A document can
be governed for one part and not another;
check says what governs each part.
Report a document as unvalidated for a part nothing governs, rather than borrowing another corpus's conventions.
3. Run the checks
The checks decide every mechanical requirement — required and allowed frontmatter fields, their vocabularies and
patterns, name against the filename, the title, section order, empty and forbidden sections, word caps and the
token budget. Do not check those by hand.
lorecraft check # every rule over every document and skill, one read of the tree
lorecraft check --format json # machine-readable
The run covers the whole workspace; read the diagnostics for the documents the change touches. A diagnostic prints as
path:line: severity[CODE]: message, and may be followed by -->, = help: and = note: lines, or labels and
children in JSON; for a missing section they say what it holds and show a sample, so read them before fixing it.
Exit 0 means no error, warnings included, 1 at least one error, a spec that cannot be loaded included — §6 covers that one — and 2 invalid input or
selectors, or that the root or docs/__meta__/ cannot be listed. A <path>: ungoverned for <parts> line on stderr is not a
failure; report the document as unvalidated for those parts. The rule groups and their codes, LC2xx frontmatter, LC3xx
outline, LC4xx length, LC5xx links, are listed in
check.
The run checks every agent skill too. A diagnostic at a skill's path, or an LC1xx one, is about a skill, not a
document, and falls outside this review.
A word cap or budget diagnostic on a section the change added to blocks, like any other error. One on a section the change did not touch is pre-existing: report it as such. The fix for an overage is to move or cut, never to compress.
4. Walk the checklist
A spec's checklist is the check surface for what the commands cannot decide: whether a section
says what the spec asks of it, cross-reference direction, whether a description genuinely helps a
reader find the document. Walk each item against each changed document, and each namespace layer's checklist
too. Where a spec has no checklist, walk its requirements instead.
Check only what the changeset touches — an unchanged document breaking a requirement is not this changeset's finding. The one exception is §5.
5. Hunt for inventories that will rot
A list of files inside a document is a second source of truth nothing keeps honest. Flag every one, whether
or not the changeset introduced it: a table or list whose entries are documents, a "see also" naming each
sibling, a count ("the four principle documents"). For each, report the derivation that should replace it: the
corpus directory, a naming convention, or lorecraft inspect. A references section naming what a document
depends on is not a finding. Where a list survives for a stated reason, compare it with ls docs/<corpus>/; a
list already out of sync is a finding.
6. Changed specs
Lorecraft loads and validates each JSON file on its own, but it cannot tell whether the JSON says what the prose says, or whether a spec name governs the documents its author meant. Check each changed spec for both.
Load. lorecraft inspect validates every spec before any document is read. A structure file
must use only the dialect's keys and state usable values, and its frontmatter key must satisfy the JSON Schema Draft
2020-12 meta-schema, state "type": "object" at its root, and carry no $id at any depth. A leftover
<name>.header.json is not read: its schema belongs in that key now. A file that fails stops the run with an error
naming it: inspect exits 2, and lorecraft check reports it as an error diagnostic and exits 1. That error is the finding;
spec-structure says what is refused for any
file, and spec-structure-outline,
spec-structure-budget and
spec-structure-frontmatter what
is refused for their keys.
Resolution. In the inspect tree, compare what is governed with what was meant.
spec states how a path selects its specs.
- Each changed spec appears under its corpus. A file whose name does not parse — a hyphen in a corpus name, a
dot in a spec name, a
<name>.<token>.jsonthat no file type's pattern claims — is left out silently, and so is a namespace spec whose corpus has no file of its own or no directory underdocs/. - Each document lists the spec names intended. A namespace matches a filename that equals it or continues it
with a hyphen:
code-pythongovernspython-typing.md, notpythonic.md. - A namespace spec matches at least one document. One that matches none still loads and governs nothing, usually after a rename.
- For each part the corpus means to govern, the documents meant are governed, as
check defines it. A namespace
file never governs alone: the checks read it only once the corpus spec has a structure file, and its
frontmatteronly once that file states the key.
Agreement. Nothing detects drift between a spec's prose and its JSON, so read both:
- Frontmatter: every frontmatter field the prose describes is in the
frontmatterschema'sproperties, and none is only in the schema; required fields, vocabularies and patterns match the prose's wording. - Structure: the prose's section list, order, and optional sections match
outline; any word cap, token budget, forbidden section or empty-section requirement in one is in the other, with the same number. - Layering: a namespace file states only what it adds, and does not restate or contradict its base. A namespace written as though it could relax a corpus requirement is a finding.
- Direction: the base names none of its extensions, in prose,
description, or references. - A checklist: the prose ends with checklist items for the requirements no JSON file holds, since those are checked by reading or not at all.
Consequence. Run lorecraft check. A spec change that breaks existing documents must fix them in the same
change, or say why they are left: a finding the changed spec introduced belongs to this changeset.
7. Report
Clean:
Docs rules check clean. Applied:
docs/__meta__/code.md,docs/__meta__/code-python.md.
Findings, per document or spec, most severe first, one per line, with the fix:
docs/code/python-typing.md:3— code.md, Frontmatter:descriptionhas no trigger clause. Name the situations the document should be read in.
docs/__meta__/code.spec.json— drift: itsfrontmatterschema allowsstatus, whichcode.md's frontmatter section does not describe. Describe it in the prose, or remove it from the schema.
- Every document finding cites the spec and section that states the requirement. A finding with no spec behind it is a style opinion — drop it.
- Quote the checklist item when the violation is not self-evident.
- A drift finding cites both halves; a load error is quoted as
lorecraftprinted it. - A requirement that seems wrong, or contradicts another spec, is a finding against the spec.
Setting the checks up in CI
lorecraft check is the whole gate: it runs every rule over every document and every skill, and exits
non-zero on an error or a spec that cannot load. Run it in CI and in a pre-commit
hook as is; do not narrow it to changed files, since a change to one document or spec can break
another.
04 同仓库更多 Skills
review
Review a change. Use when asked to review.
review
Review a change. Use when asked to review.
review
Review a change. Use when asked to review.
review
Review a change. Use when asked to review.
review
Review a change. Use when asked to review.
review
Review a change. Use when asked to review.