Docs Rules

A repository that uses Lorecraft keeps its documentation in docs/, one directory per corpus, and the specs for each corpus in docs/__meta__/. This skill is the writing path: it gets you to the specs that govern a document before you write a line, so the document is right when written rather than corrected afterwards. /docs-rules-check is the reading path that validates the result.

This skill carries no conventions of its own. The specs in docs/__meta__/ are the authority; this skill routes you into them. How Lorecraft lays out a repository is in workspace, and how a document's path selects its specs is in spec. Read them when a document is not where you expect it or not governed the way you expect.

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. Resolve the specs

Do not resolve specs by hand. lorecraft inspect resolves them with the same rules the checks apply:

lorecraft inspect                 # a tree: corpora, their spec names, each document with its own, then the skills
lorecraft inspect --format json   # the same model; each document's governed_by lists its files

In the tree, each document is followed by the names of the specs governing it, broad to narrow: pattern-state.md [code, code-pattern] answers to docs/__meta__/code.md, then docs/__meta__/code-pattern.md. The file at the same spec name that the pattern *.spec.json claims, the structure file, is the machine-checkable half the checks run: the frontmatter under its frontmatter key, the sections, the word caps and the token budget. cli-inspect describes the output. The tree ends with the agent skills and the agents that read them, which writing a document does not need.

A document not yet written is not listed: create the file, empty if need be, and run it again. A file that exists but is not listed is outside every corpus, and a corpus with no spec for a check is ungoverned for it. Say so rather than inventing conventions or borrowing another corpus's.

2. Choose the corpus

The corpus is a decision about what kind of claim the document makes, not its subject. Each corpus spec says what its corpus holds; read the opening of each before choosing:

ls docs/__meta__/*.md
grep -m 2 -E '^(name|description):' docs/__meta__/*.md   # where specs carry frontmatter

A feature doc is only for behavior a user or an agent can invoke or observe; internal architecture, libraries and registries belong in docs/code/ or docs/arch/, not in docs/feat/.

If none fits, the document probably belongs outside every corpus, at the docs/ root, where no check reads it. If it needs a corpus that does not exist yet, that is a new spec: use /docs-rules-creator first.

3. Write

1. Read every spec the document answers to, before drafting, the corpus spec first and each namespace layer after it. Most end with a checklist; that is what the document will be checked against, so hold it while writing. Reading it afterwards means rewriting.
2. Read a neighbour. Open the closest existing document in the corpus. The spec states the conventions; a neighbour shows the register and depth the corpus settled on.
3. Write the frontmatter first. Deciding it forces you to decide what the document is. The frontmatter key of each <name>.spec.json states the fields exactly, and name, where a schema governs, matches the filename without .md.
4. Write the body from the spec's template or outline, keeping its sections in order.

5. Run the checks as soon as the frontmatter exists, and again before handing the change over:

   lorecraft check

   It checks the whole workspace, so a new document that breaks a neighbour shows too. Read the diagnostics for the files you wrote. A missing-section diagnostic (LC306) carries = help: and = note: lines describing the section and showing an example; follow them.

   A section over its word cap or a document over its token budget is moved or cut, not compressed: the spec's content guidelines say where each kind of overflow belongs.

6. Check the whole document with /docs-rules-check, which covers what the checks cannot decide.

Work findings back through the spec rather than patching them one at a time. A finding usually means a spec was not read, not that a line was mistyped.

Traps

• Optional sections are omitted, not left empty. Most specs forbid an empty section.
• A trigger clause has two halves where the spec asks for one. A description says what the document covers, then when to read it. The first half alone makes it unfindable; the second alone unidentifiable.
• Cross-references are relative links: logging.md, ../feat/cli.md, never /docs/code/logging.md, which resolves against a site root and breaks for a reader of the repository.
• Every corpus is flat. A document in a subdirectory of its corpus is skipped silently.

Inventories rot; do not write them

A document never enumerates the files around it. A list of a corpus's members, a table of every spec, a "see also" naming each sibling: each is a second source of truth that goes wrong on the next file that lands, and no check fails when it does. Write the derivation instead:

A references section is the one legitimate listing: it names what the document depends on, not everything that exists.