Brummel
161ccc837b
Add a 'Render diagrams and formulas natively' section to the wiki skill: prefer native Mermaid for diagrams and KaTeX ($...$) for formulas over ASCII art / unicode-in-code, as the default (but not for the sake of it). Records the mechanics learned in practice — Mermaid label/colour discipline and real-render validation; KaTeX as a LaTeX-math subset, dollar-only delimiters, the table pipe/percent escapes, and the closing-$-glued-to-slash boundary trap — plus the two-gate validation discipline (parser gate + Gitea render-parity, table integrity, adversarial semantic-equivalence), since valid != correct != rendered. Also a checklist item and a description clause.
245 lines
14 KiB
Markdown
245 lines
14 KiB
Markdown
---
|
||
name: wiki
|
||
description: Use when writing or editing a wiki article (a Gitea/GitHub repository wiki) — invoked as `/wiki` or when the user asks to write, add, or update a wiki page. Fixes the house rules for wiki content: a wiki holds durable, PROJECT-NEUTRAL knowledge acquisition, never a snapshot of the current codebase (anything that drifts when the code moves belongs in `docs/`, not the wiki); every load-bearing fact is backed by a validated EXTERNAL source (prefer canonical/stable pages); every claim is marked law vs convention vs corrected so a rule-of-thumb is never passed as a law; articles are structured as one overview page plus thematic, cross-linked detail pages, each with a References section, written in English. Also records the mechanics — a wiki is its own `<repo>.wiki.git` git repo, pages are `.md` files addressed by slug, editable via web UI / git clone / the API — and the wiki-vs-`docs/` decision rule. Renders structure and math natively — Mermaid for diagrams, KaTeX (`$...$`) for formulas — validated against the renderer (parse + render-parity), never ASCII art or plain-char formulas. A standalone utility skill: manual invocation only, dispatches no agents, runs no pipeline phase.
|
||
---
|
||
|
||
# wiki — write durable, project-neutral wiki articles
|
||
|
||
> **Violating the letter of these rules is violating the spirit.**
|
||
|
||
## Overview
|
||
|
||
A wiki article is **durable knowledge acquisition** — a thing worth keeping that
|
||
should outlive the project, the conversation, and the current state of the code.
|
||
It is read later by people who were not there when it was written, and often by
|
||
people outside the project entirely. So it must be **project-neutral** and
|
||
**stable**: it records *what is true about a domain, method, or tool* — not *what
|
||
the current codebase happens to do today*.
|
||
|
||
This is the line that defines the skill. A wiki is **not** a mirror of the
|
||
implementation. Anything that drifts the moment the code moves — field names,
|
||
file/line anchors, build status, issue numbers, project-internal contracts — does
|
||
not belong in the wiki. That material has a home (`docs/` in the code repo, the
|
||
tracker, the design ledger); the wiki is the place for the part that stays true.
|
||
|
||
This is a standalone utility skill. It dispatches no agents and is not a pipeline
|
||
phase; it is invoked manually (`/wiki`) when a wiki page is being written or
|
||
edited. While active, every page obeys the rules below.
|
||
|
||
## The Iron Law
|
||
|
||
```
|
||
A WIKI ARTICLE IS DURABLE, PROJECT-NEUTRAL KNOWLEDGE — NEVER A SNAPSHOT OF CODE STATE.
|
||
IF IT WOULD DRIFT WHEN THE CODE MOVES, IT BELONGS IN docs/, NOT THE WIKI.
|
||
SOURCE EVERY LOAD-BEARING FACT WITH A VALIDATED EXTERNAL LINK.
|
||
MARK EACH CLAIM — LAW, CONVENTION, OR CORRECTED — NEVER PASS A RULE-OF-THUMB AS A LAW.
|
||
ONE OVERVIEW PAGE; THEMATIC DETAIL PAGES; CROSS-LINKED; A REFERENCES SECTION ON EACH.
|
||
THE WIKI IS A GIT REPO: WRITE IT IN ENGLISH, KEEP IT COMMIT-CLEAN.
|
||
```
|
||
|
||
## When to use
|
||
|
||
| Situation | Use this? |
|
||
|---|---|
|
||
| "Put this / write this up in the wiki" | Yes |
|
||
| "Add / edit a wiki page on X" | Yes |
|
||
| Capturing reusable, durable knowledge (a domain, a method, a tool) | Yes |
|
||
| Project status, design rationale, or anything coupled to the live code | **No → `docs/` / ledger / tracker** |
|
||
| A note relevant only to the current conversation | No |
|
||
|
||
## What belongs in a wiki — and what never does
|
||
|
||
The single load-bearing distinction. When in doubt, ask: *would this sentence
|
||
become false or stale when the code changes?* If yes, it is banished.
|
||
|
||
| Belongs (durable, neutral) | Banished (drifts with the code) |
|
||
|---|---|
|
||
| Domain concepts, definitions, formulas | "Today the system computes X / emits Y" |
|
||
| How a method/algorithm works | Field, type, function, or file names; line anchors (`foo.rs:42`) |
|
||
| External standards, math, derivations | Build/feature status ("built", "unbuilt", "partial", "planned") |
|
||
| Trade-offs and general decision rules | Issue / ticket / PR numbers, milestone names |
|
||
| Benchmarks & thresholds from the literature | Project-internal design contracts / invariants (e.g. `C12`) |
|
||
| Citations to primary sources | Project-specific vocabulary, product names, roadmaps, next-steps |
|
||
|
||
When a topic is genuinely useful but only its *project-specific application*
|
||
drifts, **generalize it**: state the method neutrally, name the generic inputs
|
||
(e.g. "per-period returns", "equity curve", "trade list") instead of concrete
|
||
field names, and move the project-specific mapping to `docs/`.
|
||
|
||
## Source every load-bearing fact
|
||
|
||
A wiki's value is that its facts can be trusted and traced. Every load-bearing
|
||
claim — a formula, a threshold, a definition — carries a link to an **external**
|
||
source.
|
||
|
||
- **Prefer canonical, stable pages**: encyclopedic references (Wikipedia),
|
||
primary papers (SSRN / arXiv / journals), official documentation, recognized
|
||
standards bodies. Avoid ephemeral content-farm pages.
|
||
- **Validate before citing.** Only link a URL you have confirmed loads and is
|
||
on-topic — never a remembered or guessed link. A dead or wrong citation is
|
||
worse than none.
|
||
- **Keep references navigable.** Put a `## References` section on each detail
|
||
page (grouped by section), rather than crowding inline links into dense tables.
|
||
Inline-link only the few key terms in prose.
|
||
|
||
## Mark each claim: law vs convention vs corrected
|
||
|
||
Much "common knowledge" in a domain is convention, not law. Conflating the two is
|
||
the most common way a wiki misleads. Mark claims explicitly and use a legend:
|
||
|
||
- **[L] law / exact** — a definition, identity, or derivation that does not vary.
|
||
- **[C] convention** — a practitioner rule-of-thumb that varies by context; never
|
||
state it as a hard rule, and say so.
|
||
- **[CORR] corrected** — a value that was wrong in a common source and has been
|
||
fixed here; cite the correction.
|
||
|
||
Never present a `[C]` as a `[L]`. If a threshold has no authoritative basis, say
|
||
"no standard threshold" rather than inventing one.
|
||
|
||
## Structure & style
|
||
|
||
- **One overview page + thematic detail pages.** The overview (the wiki's landing
|
||
page) carries the narrative and orients the reader; detail pages carry the dense
|
||
reference material. Keep each page single-purpose.
|
||
- **Cross-link by slug.** Wiki links are `[Text](Page-Slug)`, where the slug is
|
||
the page's file name without `.md` (spaces become `-`). Link generously between
|
||
the overview and the detail pages.
|
||
- **Heading anchors are fragile.** A link to `Page#section` depends on the exact
|
||
heading slug the renderer generates (lowercased, punctuation stripped, spaces →
|
||
`-`, and `&`/em-dashes produce surprises). Prefer linking to the page and naming
|
||
the section in prose, or verify the anchor before relying on it.
|
||
- **English.** A wiki is a git repo; its content is committed, so it is written in
|
||
English (the repo language), regardless of chat language.
|
||
- **Tone:** state facts and clearly-flagged claims; a wiki page is reference
|
||
material, not a chat message or a changelog.
|
||
|
||
## Render diagrams and formulas natively
|
||
|
||
A wiki page is read in a browser, not a terminal. Structure and math carry more
|
||
when the renderer *draws* them: a **diagram** as a real diagram, a **formula** as
|
||
typeset math — never ASCII art or unicode-in-code-font soup. Gitea and GitHub
|
||
both render two languages natively through their GFM markdown pipeline,
|
||
client-side, with no server configuration:
|
||
|
||
- **Mermaid** — a fenced ` ```mermaid ` block becomes a diagram.
|
||
- **KaTeX math** — `$...$` inline, `$$...$$` or a ` ```math ` fence for a block,
|
||
becomes typeset math.
|
||
|
||
(Other diagram languages — PlantUML, Graphviz — need server-side `[markup.*]`
|
||
config a hosted instance usually lacks; a committed `.svg`/`.png` always works as
|
||
a fallback. Probe a renderer before relying on it: POST a sample to Gitea's
|
||
`/api/v1/markdown` with `{"Mode":"gfm"}` and check it hands the block off — see
|
||
the render-parity gate below.)
|
||
|
||
Default to native rendering — **but not for the sake of it.** A diagram earns its
|
||
place only when it carries structure a sentence can't (a topology, a pipeline, a
|
||
fork); a formula is typeset only when it is a genuine expression. Decorative
|
||
diagrams, single-variable mentions, and threshold tokens stay prose or code.
|
||
|
||
### Mermaid
|
||
|
||
- Quote every node label and keep labels ASCII; use conservative flowchart
|
||
syntax. Don't set theme-fragile colors / `classDef` — let the instance theme
|
||
style it (it adapts to light/dark on its own).
|
||
- Mind edge semantics: a node arrow back to *itself* reads as the opposite of
|
||
"this node never does X" — put that meaning in the caption, not an edge.
|
||
- **Validate by real render.** A syntax slip surfaces only as a broken diagram in
|
||
the browser, so render each block to an image with `mermaid-cli` against a
|
||
system Chrome (`PUPPETEER_SKIP_DOWNLOAD=true` +
|
||
`PUPPETEER_EXECUTABLE_PATH=$(which google-chrome-stable)`) and *visually*
|
||
inspect the layout-risky ones (dense subgraphs, forks, cycles).
|
||
|
||
### KaTeX math
|
||
|
||
KaTeX is a **subset of LaTeX math** — fractions, roots, Greek, subscripts, sums,
|
||
`\binom` — *not* a LaTeX engine: no TikZ/PGF, no packages, no document
|
||
environments. Diagrams stay Mermaid/SVG; KaTeX only sets formulas.
|
||
|
||
- **Dollar delimiters only.** `$...$` / `$$...$$` / ` ```math `. The bracket forms
|
||
`\[...\]` and `\(...\)` do **not** render in Gitea.
|
||
- **Inside a Markdown table cell, never put a literal `|` in `$...$`** — it is read
|
||
as a column separator and breaks the table. Use `\lvert ... \rvert` (or `\mid`).
|
||
Likewise `%` → `\%` (a bare `%` starts a KaTeX comment).
|
||
- **Boundary trap:** a closing `$` glued directly to `/` (or a digit) suppresses
|
||
the math handoff — Gitea renders it as literal text. Keep a space or punctuation
|
||
after the closing `$`.
|
||
- Math color is theme-adaptive (KaTeX uses `currentColor`) — don't hardcode it.
|
||
- Convert only genuine formulas; leave threshold tokens (`>0.95`, `1–3`),
|
||
single-variable mentions, and descriptive pseudo-expressions as code.
|
||
|
||
**Two gates, because valid ≠ correct ≠ rendered.** A snippet can parse cleanly yet
|
||
mean the wrong thing or not render at all (`\cdotp` is a real macro that silently
|
||
swallows the next `p`; `$...$/x` parses but Gitea drops it). So:
|
||
|
||
1. **Parse gate** — run every snippet through a real KaTeX parser
|
||
(`katex.renderToString(tex, {throwOnError:true})` / the `katex` CLI). Catches
|
||
syntax errors.
|
||
2. **Render-parity gate** — POST the whole page to Gitea's `/api/v1/markdown`
|
||
(`{"Mode":"gfm"}`) and confirm the count of emitted
|
||
`<code class="language-math">` handoffs equals the number of source `$...$`
|
||
spans. Catches the boundary/handoff failures the parser cannot.
|
||
3. **Table integrity** — re-render and confirm every table keeps its column count
|
||
(a stray `|` drops or adds a column).
|
||
4. **Semantic fidelity** — when converting many formulas at once, adversarially
|
||
check each typeset result denotes the *same* mathematics as the original
|
||
(dropped term, swapped index, sign flip, mis-grouped fraction); the parser only
|
||
judges syntax. Then eyeball the gnarliest formula rendered live.
|
||
|
||
## Mechanics — a wiki is its own git repo
|
||
|
||
A repository wiki (Gitea, GitHub) is a **separate git repository** living
|
||
alongside the code repo as `<repo>.wiki.git`. Knowing this demystifies it.
|
||
|
||
- **Lazy creation.** The wiki repo does not exist until the first page is created.
|
||
Before that, cloning it or hitting the wiki API returns an error (Gitea: HTTP
|
||
500 on `ls-remote`, 404 on the API). Creating the first page initialises it.
|
||
- **A page = a Markdown file.** The page title becomes the file name with spaces
|
||
turned into `-`; the URL slug is the file name without `.md`. So title
|
||
`Metric Catalogue` → file `Metric-Catalogue.md` → URL `…/wiki/Metric-Catalogue`.
|
||
- **Three ways to edit** (all end in the same git commit):
|
||
- **Web UI** — the repo's *Wiki* tab → *New Page* / *Edit*. Lowest friction.
|
||
(Enable the wiki first under repo *Settings* if absent.)
|
||
- **Git** — `git clone <host>/<owner>/<repo>.wiki.git`, edit `*.md`, commit,
|
||
push. Best for bulk/local editing.
|
||
- **API** — Gitea: `POST /api/v1/repos/{owner}/{repo}/wiki/new` to create,
|
||
`PATCH …/wiki/page/{slug}` to edit; body is JSON
|
||
`{title, content_base64, message}` (the content is base64-encoded). Build the
|
||
body with `jq` for safe escaping; authenticate with a token
|
||
(`Authorization: token <T>`). List pages with `GET …/wiki/pages`.
|
||
- **Special pages (convention).** `Home.md` is the landing page; `_Sidebar.md` is
|
||
a navigation panel shown on every wiki page; `_Footer.md` a footer on every
|
||
page. Use `_Sidebar.md` for cross-page navigation once there are several pages.
|
||
- **Versioned.** Because it is git, every page has full history (diff/revert) — in
|
||
the UI per page, or locally via `git log`.
|
||
|
||
## Wiki vs `docs/` — choosing the home
|
||
|
||
Two homes for written knowledge; pick by coupling, and **do not maintain the same
|
||
content in both** (dual maintenance is itself a drift source).
|
||
|
||
| | Wiki (separate repo) | `docs/` (in the code repo) |
|
||
|---|---|---|
|
||
| Coupling to code | loose — drifts easily | atomic: one commit/PR changes code **and** doc together |
|
||
| Review | outside the PR diff | in the diff, reviewed with the code |
|
||
| History | its own, separate | shared with the code |
|
||
| Code anchors (`file:line`, contracts) | go stale unnoticed | move with the tree |
|
||
| Edit friction | low (browser, no review) | higher (commit path) |
|
||
|
||
**Rule of thumb:** *living, loosely-coupled, durable knowledge → wiki; anything
|
||
that must stay in lockstep with the code → `docs/`.* The wiki is for what stays
|
||
true; `docs/` is for what tracks the implementation.
|
||
|
||
## Before publishing — checklist
|
||
|
||
1. No implementation state (names, line anchors, status, issue numbers,
|
||
project-internal contracts, project vocabulary). Generalize or move to `docs/`.
|
||
2. Every load-bearing fact has a validated external link; the page has a
|
||
`## References` section.
|
||
3. Every threshold/claim is marked `[L]`/`[C]`/`[CORR]` with a legend.
|
||
4. Cross-links resolve (slugs correct; heading anchors verified or avoided).
|
||
5. Written in English; reads as reference material.
|
||
6. Diagrams render as native Mermaid and formulas as native KaTeX (no ASCII-art
|
||
diagrams or unicode-in-code formulas where native rendering fits), each
|
||
validated against the renderer — parse gate, render-parity gate, table
|
||
integrity.
|