From ff623e9c696d912dabebf32e5c03dea5b95efb6b Mon Sep 17 00:00:00 2001 From: Brummel Date: Mon, 15 Jun 2026 14:01:39 +0200 Subject: [PATCH] feat(wiki): add wiki skill for durable, project-neutral wiki articles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 .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. --- README.md | 8 ++- wiki/SKILL.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 173 insertions(+), 3 deletions(-) create mode 100644 wiki/SKILL.md diff --git a/README.md b/README.md index 068893b..25c7fe2 100644 --- a/README.md +++ b/README.md @@ -30,9 +30,11 @@ The pipeline skills, each with the agents it primarily dispatches: | `docwriter` | API surface stable across N cycles | rustdoc / docstring sweep | Optional | | `boss` | User types `/boss` | autonomous-orchestrator session — dispatches the other skills until done-state or bounce-back; can optionally sign specs in the user's place (opt-in, see below) | User-invoked, never auto-dispatched | -Two further **utility skills** are invoked on demand rather than as -pipeline phases: `issue` (file or update a tracker item) and `glossary` -(build or maintain the project glossary — see `docs/glossary-convention.md`). +Three further **utility skills** are invoked on demand rather than as +pipeline phases: `issue` (file or update a tracker item), `glossary` +(build or maintain the project glossary — see `docs/glossary-convention.md`), +and `wiki` (write or edit a repository-wiki article — durable, project-neutral, +sourced knowledge, deliberately kept out of `docs/` and the pipeline). One **conversational skill** stands outside the pipeline entirely: `pseudo` (typed `/pseudo`) switches replies into commented, diff --git a/wiki/SKILL.md b/wiki/SKILL.md new file mode 100644 index 0000000..148115d --- /dev/null +++ b/wiki/SKILL.md @@ -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 `.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 `.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 //.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 `). 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.