oikos/.agents/shared/writing-style.md

Writing Style

Write like a technical reference, not a marketing page. Every sentence conveys new information. These rules govern committed documentation — wiki pages, READMEs, schemas, skills, AGENTS.md, plans, investigations, and code comments. They are separate from caveman.md, which governs an agent's chat responses; the two do not conflict.

New or rewritten pages follow these patterns from day one. Existing pages get updated the next time they are touched.

Vocabulary — never use these

• Significance puffers: "pivotal", "crucial", "vital", "groundbreaking", "transformative", "testament", "paramount", "invaluable".
• Analytical verbs: "delve", "leverage", "utilize", "facilitate", "foster", "showcase", "underscore", "streamline", "harness".
• Poetic nouns: "tapestry", "landscape" (figurative), "realm", "paradigm", "ecosystem" (figurative), "journey" (figurative), "nexus", "cornerstone".
• Promotional adjectives: "robust", "seamless", "innovative", "cutting-edge", "meticulous", "holistic", "comprehensive".
• Opening crutches: "In today's world", "In the ever-evolving landscape of", "It's worth noting that", "It is important to note that".

Use short, common words: "use" not "utilize", "help" not "facilitate", "show" not "demonstrate".

Voice

Describe what systems do and how they work.

• Reference prose (node pages, cross-cutting infrastructure descriptions, ## Role, ## Why, At a glance) is third-person: state facts about the system, not instructions to a reader.
• Recipes, runbooks, and skills are the exception: second-person imperative is allowed and preferred where it makes a procedure clearer ("Edit the Caddyfile, commit + push", "Verify with dig +short"). This matches how the operator actually works. The vocabulary, structure, and cross-reference rules below still apply.

Page shape

Every doc-level page follows the same shape so a reader scans it in one pass.

1. One H1 = the page title. Node pages use # <id> — \`; topic pages use # `.
2. Opening definition. First paragraph, 1–3 sentences, says what the thing is. No motivation, no marketing, no setup.
3. Body sections in the natural order for the topic. Reuse the section templates in page-templates.md.
4. ## Changelog at the bottom of every node/topic page — reverse-chronological, append-only. This section is machine-parsed (get_changelog in mcp/server.py); keep the ### YYYY-MM-DD — title shape.
5. Related links only at the bottom, only when a reference cannot be woven inline.

Section indexes (folder READMEs)

A folder's README.md opens with a 1–3 sentence prose intro that says what the section covers, then a single navigation table — | Document | What it covers | — and nothing else. No stale counts, no duplicated prose, no narrative between the intro and the table.

Structure rules

• Make every sentence information-dense. Cut filler, qualifiers, and setup phrases. Lead with the concrete fact or action, not why it matters.
• No participial tack-ons (", highlighting the importance of…"). If the clause adds information, make it a separate sentence.
• No meta-commentary about the content itself. Do not narrate the page's own structure or linking strategy.
• Prefer tables for enumerable items with internal structure (service/port maps, field lists, status grids). Reserve bullets for short non-structured lists.
• Use the bold-leading-phrase pattern for structured points: **Read-only by construction.** The MCP server never mutates state. — a bold noun phrase, a period, then the explanation.
• When enumerating across services or nodes, give each its own ### sub-section or a table row, not one run-on paragraph.
• Use backticks for code, paths, hostnames, and file names (inventory.yaml, 192.168.8.77, pct config); italics for first-mention terminology.
• Use > blockquotes for caveats and gaps that interrupt the main flow: > **Outstanding gap.** DNS-vs-inventory drift check not yet wired. One thought per blockquote.

Diagrams

• Mermaid is the default for topology and flow diagrams. infrastructure/topology.md is generated by oikos/gen-topology.py — do not hand-edit it.
• ASCII box diagrams are fine for small shape diagrams; keep them to one screen.

Sourcing and cross-references

• Factual discipline. Every claim is grounded in a cited source, an adjacent linked page, or a directly observable fact (pct config, docker inspect, running config). Do not write sentences that sound sourced but are inference. When docs disagree with live state, fix the doc and note it in the changelog.
• One-sided cross-references. When two pages relate, the link lives in the page where the connection makes organizational sense. Do not add a back-pointer unless that direction also carries content the reader needs.
• Cross-references are content, not catalog. Inline links arise from the surrounding prose; the linked page must be needed to understand the current sentence. A bottom-of-page "Related" list is the fallback, not the default.
• Pages link with standard relative markdown links (e.g. a container page links to ../infrastructure/dns.md), forming a navigable graph. Orphans are a bug.

Code comments and commit/PR prose

• Comments explain intent, trade-offs, or constraints the code cannot convey. No diff narration, no type restatement, no section-divider comments.
• Commit messages and PR descriptions are problem → change → risk → verification, not a file-by-file diff restatement.
• The banned vocabulary applies the same way in comments and commit messages.