Docs Wg

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.

• A model, not an explanation. The strongest specs are models — a canonical vocabulary, a small generating rule or set of invariants, contract tables, and conformance clauses — the kind of thing a second implementer runs in their head. A doc that explains the code has the arrow backwards: the code conforms to the spec, never the reverse. Prose justifies the model; it does not substitute for it.
• 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 the engine repo's docs/wg/research/** (github.com/gridaco/nothing), 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.

Name the genre — and don't let one wear another's costume. A cluster also collects legitimate non-spec artifacts: methodology, a decision record, an inventory, an RFD (a design proposal still under discussion). Each is fine — but it must say what it is. An inventory or a decision-memo dressed as a normative spec, numbered with "contracts" it cannot enforce, misleads everyone who tries to conform to it. If a doc is not a model, label it and drop the costume.

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.
• Implementation-binding specs. A spec that binds a universal contract to one codebase — the concrete data an undo entry is, this build's default keymap, the mapping from contracts to running code — is code-specific by nature. It belongs with the code (a docs/ folder in the package or crate, next to what it binds), not under docs/wg. The WG tree stays code-agnostic; the binding lives where it can name files honestly and move with them.

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.