| name | writing-docs |
| description | Repository documentation contract for the Tattletale monorepo: the house style for doc comments, module headers, inline comments, and any committed prose (what-over-how, contracts over narration, banned-vocabulary blocklist, format rules, seven canonical reference files). Use when writing or updating doc comments, module headers, inline comments, or any prose in this repo, or when de-sloping existing comments. |
| license | MIT |
| compatibility | opencode |
| metadata | {"audience":"developers","workflow":"documentation"} |
Writing Docs (Tattletale House Style)
What I do
This skill is the repository documentation contract. It distills the style of
the seven canonical files (REFERENCE.md) plus the Write Without Hidden Context
framing below into one enforceable standard: comments for a developer who just
cloned the repo, no history, no pipeline labels, no campaign vocabulary.
When to use me
Use when writing or updating any committed prose (doc comments, module
headers, inline comments, type docs, kernel docs, Lean comments, test file
headers, commit messages) or when de-sloping existing comments.
Golden rules
- Think who is your audience. A user of the API gets
## docs on how
to use it correctly, never a drowning in how it is done. A maintainer
gets # comments; use industry-standard jargon, never invented jargon.
- Write without hidden context. If someone who pulls the repo cannot
understand a sentence, rewrite it.
- A wall of text is hostile to the reader. Strongly prefer diagrams and
charts for lifecycles, dataflow, multidimensional algorithms and data
structures, and bullet points for contracts.
Quick start
- Write the doc as a contract: what the code does, its preconditions,
postconditions, invariants, shapes, layout facts. Never narrate the
journey.
- Open a module header with a noun phrase (
PagedRadixTrie — a compressed Radix/Patricia trie ...), never with The.
- Module headers 3-8 tight lines; test headers carry the run command only;
test docs scale with test complexity.
- Before committing: grep the banned vocabulary (EXAMPLES.md) and run the
self-check (REFERENCE.md).
Write Without Hidden Context
Applies to all repository prose: documentation, comments, docstrings, commit
and PR text, plans, reports, names, errors, technical summaries. Everything
must make sense to a technically capable reader who has the repository but
none of the conversation or development history.
- Describe the system as it exists: purpose, behavior, invariants,
interfaces, evidence, limitations. Do not narrate the journey.
- No lifecycle labels as identities:
Phase 2, pilot, next, current,
new, old, latest are not technical names.
- No false definite references:
the 1M-token capture, the experiment,
this approach are invalid unless the exact object was introduced locally
and unambiguously. Counts, dates, and versions are attributes, not
identities.
- On first reference, give the object's semantic role and its durable
identifier: artifact name, path, schema, revision, manifest, or hash.
- Explain concepts before identifiers. Codenames, experiment labels, and
implementation shorthand such as
XOR-Cheb-T12 are never the vocabulary of
the design; mention literal identifiers only after describing what they
mean, and only when the reader must use them.
- Canonical documentation is a present-state specification, not a changelog.
Replace stale claims instead of layering history on top. Chronology,
rejected attempts, and retrospectives belong only in explicitly historical
documents.
- Label status explicitly:
implemented, qualified, research-only,
unsupported. State evidence as conditions, measurement, result,
conclusion, not as a story.
- Comments explain invariants, intent, and non-obvious constraints, never
change history. TODOs name the missing condition and removal criterion.
- Commits and PRs state the resulting behavior, technical reason,
compatibility impact, and validation. They do not recount attempts or
pivots.
Final test: if understanding any sentence requires "you had to be there,"
rewrite it.
The contract
- What, not how. State what the code does and the contract it upholds.
Narration of an invisible strategy, dataflow, or lifecycle is legitimate
(a scheduler's strategy, a sync path whose failure mode is deadlock).
- Contracts over narration. Preconditions, postconditions, invariants,
ownership, shapes, lifecycle. Enumerations and layout facts are bullets or
tables, one concept per bullet.
- Never open a description with
The. Start with what the thing is
(Compile-time record: ...). A value-returning function opens with
Returns ....
- Depth scales with reader need. One line for self-evident failure
modes; full explanation for invisible ones (concurrency, memory ordering,
asm correctness). State and prove non-obvious math.
- No hidden context. No finding IDs, iteration labels, history or
journey narration, temporal words, or unverifiable claims (perf numbers
need a referenced benchmark).
- Audience syntax.
##//// is for API users, #/// for maintainers
and auditors. A ## comment never points at test files or unrelated
subsystems; a contract reference to a paired module (pack ↔ ukernel) is
legitimate.
- The name carries the doc. When the identifier says what it is, drop
the comment that restates it. Public items still need a doc comment
stating the contract; this rule only bans re-explaining visible structure.
- Banned vocabulary. The hard blocklist (EXAMPLES.md) is absolute for
consumer-authored prose; this skill's own rule definitions and examples
are exempt.
- Format rules. Parentheses stay whole, no
; or em-dashes in prose,
lines break at phrase boundaries (cap 128 chars), bullets for
enumerations. Details in REFERENCE.md.
- Test docs scale with test complexity. An element-wise tile op or a
kernel-vs-reference match needs setup, the reference call, the tolerance,
done. Elaborate docs only for genuinely intricate machinery. When in
doubt, cut.
Advanced features
- Per-domain patterns (module headers, SME2 kernels, tensor ops, transformer
layers, stateful modules + Lean), format rules, canonical references, and
the full self-check: See REFERENCE.md
- Banned-vocabulary replacement table and before/after examples: See
EXAMPLES.md
