Documents and provenance

Every durable document MUST open with frontmatter declaring title, kind, issued, author and status.

kind is standard, guide, note, decision, prompt or design. issued and author are what let a reader weigh the document; status is what stops them acting on something already overtaken. The field names match STD-001 deliberately, so one parser reads the whole corpus.

---
title: "skills CLI: technical implementation guide"
kind: note
issued: "2026-06-25"
author: W. Schenk
status: Current
verified: "2026-06-25"
---

A research note MUST cite its sources.

A note whose claims cannot be traced is an opinion with a date on it. Cite the primary source — the vendor's documentation, the source file, the API response — not a summary of it, and link it so the next reader can check whether it still says that.

A research note MUST record when its claims were last checked against reality, in a verified field.

issued says when it was written; verified says when someone last confirmed it was still true. For anything documenting a third-party tool these diverge fast, and a reader deciding whether to trust a note needs the second date far more than the first.

A research note filename MUST carry its issue date in YYYY-MM-DD form after its number.

NOTE-002-2026-06-25-skills-cli-technical-guide.md. A note is a capture of a moment: what was true, when it was checked. The date belongs in the name because staleness is the first thing a reader needs and ls should show it without opening anything. A guide or a decision record carries no date in its name — it is a topic that gets revised in place, and a date on it would only record when somebody last thought about it.

A decision record MUST state the decision, the alternatives that were considered, and what would change the answer.

The alternatives are the expensive part to reconstruct and the part that stops the same argument being had twice. "What would change the answer" is what makes the record useful when circumstances move — without it, a reader can only guess whether the decision still applies.

A decision record MUST NOT be edited to reverse its decision.

Supersede it with a new record that references it, exactly as a standard is obsoleted rather than rewritten. Editing history so that a decision was always what we now think destroys the only evidence of how the thinking changed, which is usually the most valuable thing in the file.

A superseded document MUST carry status: Superseded and name what replaced it.

The replacement is what a reader landed on the old document actually needs. A document marked superseded with no forward pointer sends them to search, and they will find the old one again.

A document that records a decision an agent made autonomously MUST say so.

Provenance includes who decided. A choice an agent made under stated assumptions and a choice a person made are different kinds of fact, and the first is the one worth revisiting first when something turns out wrong.

Content moved between documents MUST be carried over, not summarised from memory.

Migration copies; it does not paraphrase. When rules are lifted out of a guide into a standard, the guide keeps its walkthrough intact — the commands, the flags, the reasons a setting exists. This clause was written immediately after its own violation: deployment.md was replaced by a hand-written summary and lost all fifteen of its procedural details, including a shell activation line whose absence would silently break secret resolution. Diff the old file against the new one before deleting anything.

git show HEAD:path/to/old.md > /tmp/old.md && diff /tmp/old.md path/to/new.md

Every durable document MUST carry a number field and MUST lead its filename with its class prefix and that number.

GDE-002, NOTE-005, ADR-001, PRM-001 — the prefixes are fixed by section

1. A number is an address that survives a retitling, which a slug does not: a

guide renamed from deployment to local-environment is the same document, and a citation written against it should not die of that. The prefix is part of the address because GDE-002 and STD-002 are different documents, and a bare 002 in a sentence tells a reader nothing. A standard carries its number in the standard field instead, per STD-001 §3.18 — the same fact under the name it was given first.

The design document is the one exception: it is a singleton at a fixed path, cited everywhere as DESIGN.md, and a number on a class with one member addresses nothing that the path does not already address.

A number MUST NOT be reassigned once issued.

Numbers are identity, not order. A retired document keeps its number and its status says it is retired; the next document takes the next free number. Reusing one makes every citation written before the reuse resolve to the wrong document, silently, which is worse than a citation that resolves to nothing.

Every skill under skills/ MUST be registered in skills/VENDORED.md with a unique SKL number.

The number cannot live in SKILL.md: the skills CLI owns that frontmatter, and a second schema in it would break installation. So the register is a separate file, and a register nothing checks is a register that drifts — mise run skills:check fails when a skill on disk is unregistered, registered twice, or shares a number. A skill is still installed and cited by name; the number is what the published site addresses it by.

mise run skills:check