| name | documentation-style |
| description | SLD-grounded per-artifact-type documentation style guide: the four-axis Why/What/Test + Spec-References inline model, plus focused conventions for specs, READMEs, files, classes, methods/functions, and block comments. Use when writing or reviewing any documentation artifact. |
| user-invocable | false |
| version | 1.0.0 |
| category | agent-reference |
| tags | ["documentation","sld","spec-linked-documentation","style-guide","agent-reference"] |
| effort | medium |
| spec_refs | [{"id":"SPEC-SLD-02~draft","path":"docs/specs/spec-linked-documentation.md","anchor":"SPEC-SLD-02~draft","note":"Canonical spec-reference grammar this skill's Spec-References guidance defers to; this skill restates none of it."}] |
Documentation Style
Per-artifact-type documentation conventions, unified around one model: every
doc comment carries Why, What, and Test (this project's mandatory
triple where it applies), plus an optional fourth axis — a Spec References
link-back — when, and only when, a real spec governs the artifact.
This skill is a style guide, not a linkage standard. Where a project defines a
spec-linked-documentation (SLD) convention, this skill defers to it and
restates none of its grammar. In this repo that convention is DOC-38
(docs/specs/spec-linked-documentation.md) — read it directly for the actual
reference grammar, frontmatter schema, and per-language idioms. If your
project has no such convention, skip the Spec References axis entirely; the
Why/What/Test triple (or your project's equivalent) stands on its own.
The Four-Axis Model
| Axis | Answers | Mandatory? |
|---|
| Why | What problem does this solve? What's the motivation? | Yes for non-obvious code; lighter touch OK for trivial items |
| What | What does it mechanically do? | Yes for non-obvious code; lighter touch OK for trivial items |
| Test | Where is this proven? (backtick-quoted test name(s)) | Yes for non-obvious code; lighter touch OK for trivial items |
| Spec References | Which spec section governs this, if any? | Opt-in — only when a real spec governs it |
Proportionality principle: Documentation effort scales with how surprising the
code is. For self-evident items (obvious one-liners, trivial getters, thin facades),
a single-line summary suffices; for API entry points and design-heavy code, the
full Why/What/Test pattern is mandatory. Why/What/Test stay exactly what
your project's convention defines when invoked — the proportionality amendment only
gates when each axis is required. Spec References is a fourth, additive
axis: a separate block within the same doc comment, introduced by its own marker,
never a replacement for the other three.
Full pattern (API entry point with governing spec, all axes):
() { … }
