Jarvis Doc Author

Jarvis Doc Author

When a Jarvis doc is written, the rule is: classify first, then structure, then phrase, then self-check. Not the other way around.

This skill provides the scaffolding. It does not replace thinking — it enforces the discipline that separates a pile of internal Markdown files from a real doc layer (role models: Kubernetes doc site, Docker manuals, GitHub Docs).

When to trigger

Activate this skill when the user (via voice or chat) or a Sub-Jarvis explicitly or implicitly wants to write a new doc or structurally rework an existing doc. Concrete examples:

• "Schreib ein Doc ueber den BrainManager-Routing-Discipline-Mechanismus." (Write a doc about the BrainManager routing discipline mechanism.)
• "Leg ein ADR an fuer die Sub-Jarvis-Hard-Cap-Entscheidung." (Create an ADR for the Sub-Jarvis hard-cap decision.)
• "Dokumentiere wie man einen neuen Brain-Provider hinzufuegt." (Document how to add a new brain provider.)
• "Fass die Phase-6-Ergebnisse als Test-Report zusammen." (Summarize the Phase 6 results as a test report.)
• "Mach mir eine How-To fuer das Voice-Bridge-Setup." (Create a how-to for the voice-bridge setup.)
• A Sub-Jarvis receives the task from the main Jarvis "schreib das in docs/... rein" (write this into docs/...) — then the Sub-Jarvis consults this skill before writing.

Do NOT trigger on:

• Code comments, docstrings, type hints — those follow the AGENTS.md rule (code identifiers in English), but need no doc scaffold.
• Commit messages and PR descriptions — those are build artifacts.
• Memory entries — the auto-memory is responsible for those.
• Skill authoring — the skill-creator skill exists for that.
• Voice-output-filter templates or TTS prompts.

Workflow (5 phases)

1. Classify — which Diataxis quadrant?

Question: what does the reader who later opens this doc want to do or understand? Exactly one quadrant wins:

If unsure between tutorial and how-to: does the reader consult the doc while working (time pressure, problem in mind) → how-to. Does the reader go through it away from work to learn → tutorial. (Diataxis test, see references/diataxis-quadrants.md.)

Hard Rule: A doc serves exactly one quadrant. If the doc threatens to serve two, split it into two files with a cross-link. Quadrant mixing is anti-pattern AP-D-1 (see references/templates.md).

2. Determine the path

By quadrant + component. The conventions in the repo (as of 2026-04-28):

The slug is always lowercase, kebab-case, English (router-discipline, not Router-Disziplin). Never rename a slug — cross-links break otherwise.

For an ADR: check in docs/adr/ which number is next free (ls docs/adr/). Currently ADR-0001 through ADR-0012 are in use; the next free one is ADR-0013.

3. Fill in the frontmatter schema

Every Jarvis doc carries a YAML frontmatter with 7 mandatory fields:

---
title: "Concept: Router-Discipline"        # display title, in quotes
slug: router-discipline                     # URL-stable, kebab-case, append-only
diataxis: explanation                       # tutorial|howto|reference|explanation|troubleshooting|adr
status: draft                               # draft|active|deprecated
owner: harald                               # who is responsible for correctness
last_reviewed: 2026-04-28                   # ISO date YYYY-MM-DD
phase: 5                                    # master-plan phase: 0|1|1a|1c|2|3|4|5|6|7|L+P|A0..A5|-
---

Optional: tags, related (cross-refs as a list of slugs), deprecates, deprecated_by, audience (developer/operator/end-user — default developer for internal docs), next_review_due (computed from last_reviewed + cadence from config).

Full field definitions + rationale + examples: references/frontmatter-schema.md.

4. Insert the skeleton + write the content

Load the template for the chosen quadrant from references/templates.md (all 6 skeletons, copy-paste-ready). Mandatory and optional sections are marked. Fill in this order:

1. # H1 = title from frontmatter (no emoji, no Markdown in the title).
2. 1-2-sentence intro directly under H1, before any H2. Answers: what is the doc, who is it for, what does the reader take away? No "Welcome", no "This document describes..." — straight to the point.
3. Quadrant-specific mandatory sections (see templates).
4. Code blocks ALWAYS with a language tag (```python, ```bash, ```toml, ```yaml, ```json). Never bare triple backticks.
5. ## What's next as a footer block, max 5 bullets, each with a cross-link to a follow-up doc (relative path, not an absolute URL).

Language rules (excerpt — full set in references/templates.md):

• Active voice + imperative in how-tos and tutorials. "Activate the voice pipeline with set JARVIS_VOICE=1" — not passive constructions.
• You form — no "the user", no "we" when the reader is meant.
• Code identifiers in English (BrainManager, jarvis.toml, EventBus), prose in English. Identifiers in backticks, never italics.
• Spell out acronyms on first occurrence ("Speech-to-Text (STT)").
• No "obviously" / "simply" / "just" — it humiliates the reader who is struggling and is explicitly forbidden in the Microsoft + Google style guides.
• No "click here" / "see this link" — the link text describes the target: "see ADR-0011 Router-Discipline", not "see here".