feat(wiki): add wiki skill for durable, project-neutral wiki articles
Standalone utility skill (manual /wiki, not a pipeline phase). Fixes the house rules for repository-wiki articles: durable project-neutral knowledge only (no implementation state — that belongs in docs/), every load-bearing fact backed by a validated external source, claims marked law/convention/corrected, an overview page plus cross-linked detail pages each with a References section, written in English. Documents the wiki mechanics (own <repo>.wiki.git, slugs, edit paths, special files) and the wiki-vs-docs/ decision rule. README: list `wiki` among the on-demand utility skills, kept out of the pipeline table.
This commit is contained in:
+168
@@ -0,0 +1,168 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user