Doctrine for drafting and keeping working-group docs under `docs/wg/**` — RFC/RFD specs and findings/research/glossary. A WG doc is a language-agnostic, code-agnostic study of a domain: it argues *why* and defines *what*, never *how in our code*. Use when writing or editing anything under `docs/wg/`, an RFC/RFD, a spec, a design note, a glossary, or research findings — including "write up the design", "document the spec", or "capture what we learned". Not for plans/TODOs (untracked `*.plan.md`), user docs, or SDK API refs — use `docs` to route those.
Doctrine for drafting and keeping working-group docs under `docs/wg/**` — RFC/RFD specs and findings/research/glossary. A WG doc is a language-agnostic, code-agnostic study of a domain: it argues *why* and defines *what*, never *how in our code*. Use when writing or editing anything under `docs/wg/`, an RFC/RFD, a spec, a design note, a glossary, or research findings — including "write up the design", "document the spec", or "capture what we learned". Not for plans/TODOs (untracked `*.plan.md`), user docs, or SDK API refs — use `docs` to route those.
WG docs
Working-group docs are where Grida reasons about a problem before and
above any one implementation. A good WG doc could be handed to someone
rebuilding the feature in a different language, on a different stack, in a
different decade, and still be the right starting point. That is the bar.
The reason WG docs are code-agnostic is not stylistic. Code moves; a file
path or a function name is stale within months, and a doc anchored to it
rots into a lie. A doc anchored to the domain — the problem, the spec,
the why — stays true as long as the problem does. You are writing the
thing that outlives the code.
This skill is the doctrine. Operational mechanics (frontmatter,
format: md, draft/unlisted/doc_tasks, the sync model) live in
docs/AGENTS.md — read it once. For reading
the WG tree before you edit, use grounding.
The two genres
A WG doc is almost always one of these. Name which before you draft —
they have different shapes.
1. RFC / RFD — spec
A specification of what a feature or system is and why it is that
way. Spec-rich. It defines vocabulary, states constraints and
invariants, and argues the design tradeoffs. It reads like a standards
document, not like a code comment.
Covers why and what. The motivation, the requirements, the model,
the chosen design and the alternatives rejected (and why).
No code-level implementation detail. Describe the behavior and the
contract, not the functions that will realize them. If you find
yourself naming a struct or a file, you have dropped from spec altitude
into implementation — climb back up.
Language- and stack-agnostic. Express the model in terms a second
implementer could honor, not in terms of the current one.
2. Findings / research / glossary
Grounded, concise domain knowledge — what is true about the problem
space. A glossary that pins down vocabulary; findings that record what a
study established; research that surveys how the domain is understood.
Always factual and grounded. Every claim traceable to a spec, a
standard, or a demonstrated result — not to a hunch or a memory.
Concise and managed. This is reference material; it earns its keep
by being correct and findable, not long.
Domain-first. It studies the problem, not Grida's solution to it.
The dedicated upstream-survey subtree is docs/wg/research/**, and
it has its own stricter rules (pure survey, Grida absent from the body).
When writing there, use research — it governs
that subtree specifically. This skill governs the broader WG surface.
What a good WG doc is
Clear and well-researched — the reader trusts it because it shows
its grounding.
Always factual; agnostic spec; language-agnostic — true regardless
of who implements it or in what.
A deep study and a starting place — the canonical entry point for
understanding a feature or spec, covering why and what.
A manifesto / doctrine when that is what the topic needs — a WG doc
may take a position and argue it. Taking a stance is allowed; the stance
must rest on fact.
What a bad WG doc is
These are not style nits — each one is the doc rotting or pointing the
reader wrong:
References specific parts of the code. File paths, function names,
line numbers. They date the doc and pull it down to implementation
altitude. Describe the contract, not the call site.
References an external project as the model. A WG doc studies the
domain, not some other project's take on it. Citing "how library X
does it" smuggles a foreign implementation in as if it were the spec.
Exception: domain reference standards. Citing a de-facto standard
or reference implementation of the domain itself is fine and often
necessary — Chromium and the W3C/WHATWG specs for web rendering, for
example, are the domain. The test: are you citing the standard, or
a project's opinion? Dedicated surveys of such sources belong in
docs/wg/research/** under research.
Dirty plans / TODO sprawl. Scattered "TODO: fix this later" and
half-formed task lists turn a reference into a scratchpad. Keep the doc
a clean statement of what is true and intended.
What is NOT a WG doc at all
These do not belong under docs/wg/ in any form. They are a different
kind of artifact:
Plans. Implementation plans live in *.plan.md files, which are
gitignored on purpose (.gitignore) — they are
working scratch, not committed knowledge. A plan is about the work; a
WG doc is about the thing.
TODO lists. Tracked work belongs in issues/PRs, not in a doc.
Conversational logs / history / decision diaries. "On Tuesday we
decided…" is process, not knowledge. Historical snapshots that must be
kept go under a _history/ folder marked unlisted: true (see
docs/AGENTS.md), never in the live spec.
The throughline: a WG doc states what is true and what is intended,
in domain terms, for a reader who arrives cold. Anything that is about
the work rather than about the thing is a different artifact.
Placement and upkeep
WG docs live in topic clusters: docs/wg/feat-*/, docs/wg/format/,
docs/wg/platform/, docs/wg/ai/, and surveys in
docs/wg/research/. Put the doc in the cluster that owns its topic;
create a new feat-<topic>/ cluster when none fits (consult
naming for the cluster name).
Most clusters have an index.md hub. When you add a doc, update the
hub so the cluster stays navigable — an orphaned doc is an unfindable
doc.
Frontmatter (per docs/AGENTS.md):
title, a description, tags: [internal, wg, <topic>…] drawn from
the controlled vocabulary in docs/tags.yml,
and format: md for plain-Markdown pages (the MDX-safety opt-out).
Links follow the links skill: relative within
/docs, GitHub-absolute for anything outside /docs, universal /_/
routes for "open in the product."
Before you save — review
Could a second implementer in another language honor this doc
without reading our code? If not, you have implementation detail to
remove.
Search the draft for file paths, function/struct names, crates/,
editor/, packages/. Each match must justify itself — usually by
being lifted to a domain-level statement.
Any external project cited as the model rather than as a domain
standard? Reframe to the domain, or move a genuine survey to
research/.
Any TODO, plan fragment, or "we decided on "? Remove it —
it belongs in a plan, an issue, or _history/.
Did you update the cluster index.md?
Related skills
docs (the family router — start there if unsure this
is even a WG doc), research (the research/
upstream-survey subtree), grounding (read and
reconcile before editing), links,
naming (cluster and concept names).
Operational mechanics: docs/AGENTS.md.
