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. 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.

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.