Skills/wiki/SKILL.md

---

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.