Knowledge Ops

Knowledge Ops — Garden the 02-DOCS Wiki

The engine is already running. harness built the 02-DOCS/ wiki and owns its automation — the inbox sweep, deterministic lint, scoring, gap detection, the self-improve loop — and changing that machinery or filling the wiki in bulk stays with it. Yours are the four judgments automation deliberately leaves to a human: what is worth capturing, how it should be shaped, how it connects, and what should retire. You are the gardener, not the machinery.

Before you touch anything

1. Confirm 02-DOCS/wiki/ exists. If there is no wiki, stop and say: "Run harness to build the 02-DOCS/ wiki first, then come back to garden it." Why: this skill operates an existing engine; it never creates one. See ../harness/SKILL.md.
2. Read wiki/harness/user-profile.md to set your verbosity (the harness accompaniment dial, L0–L3). Why: a non-technical owner wants decisions narrated; an expert wants terse diffs.
3. Read wiki/index.md and wiki/scores.json before any edit. Why: you garden from the map and the score signal, never blind. scores.json tells you what is bloated, orphaned, or stale.

If wiki/log.md shows a Maintenance Pass ran in the last few minutes, let it finish — do not race the automation.

The four operations

Every gardening request is one of four operations. Identify which before you act.

Whichever you do, record a line in wiki/log.md under the reserved-file rule in Safety rails below. The exact entry shapes per operation live in references/gardening-playbook.md.

Capture — the bar is high

Default is NO. Capture only what a future reader or agent will need and cannot cheaply re-derive. Why: the wiki is a compounding model, not a dump — the Karpathy chaos→knowledge paradigm has the LLM write and the human read, so every page must earn its keep.

Walk the altitude ladder, lowest rung first; stop at the first that fits:

1. Discard — ephemeral, re-derivable, or already covered. Most things stop here.
2. Leave in raw/ only — a source worth keeping but not worth a synthesized article yet. It stays immutable in raw/<topic>/, no wiki/ page.
3. Merge into an existing article — adds a section or fact to a page that already exists. Prefer this over a new page.
4. New article — last resort: a genuinely new, single-thesis subject with no home. Any new article follows the OKF v0.1 article template (../harness/references/wiki-article-template.md): YAML frontmatter with a non-empty type:, the OKF-recommended title/description/tags/timestamp, and standard markdown links — never wikilinks. The reserved index.md stays frontmatter-free.

Worked examples for each rung are in references/gardening-playbook.md.

Topic choice. Reuse an existing topic before inventing one, and keep wiki/ exactly one level of subdirs deep (the protocol's rule).

• Bad: wiki/payments/stripe/webhooks/retries.md (four levels deep).
• Good: wiki/payments/stripe-webhook-retries.md (existing payments/ topic, one level).

Structure — title, Overview, split, merge

Split an article when any of these is true:

• It carries ≥2 unrelated theses (e.g. "Stripe retries" and "our refund SLA").
• Its ## Overview cannot be written as one honest paragraph.
• It has grown past readability and the score signal flags it.

Why: one article = one thesis keeps scoring, linking, and retrieval meaningful. After a split, fix > Sources: and > Raw: on both halves and repair ## See Also so they reference each other. Recipe in the playbook.

Merge near-duplicates into the higher-scored page; fold the loser's unique content in, then archive the loser to wiki/<topic>/_archive/<loser>__YYYY-MM-DD.md and redirect every inbound link to the survivor. Why: never lose history, never keep two competing truths.

Title. A title is the article's address — make it a specific noun phrase, not a label.

• Bad: Notes on stuff.md, Misc.md, Stripe.md.
• Good: stripe-webhook-retry-policy.md, refund-sla-and-escalation.md.

Link — build the web, kill orphans

Every article earns ≥1 inbound link or is a conscious leaf you can justify. Why: an orphan is dead knowledge — nothing reaches it, so it scores orphan_penalty = 5 and never improves.

• Use scores.json as your worklist: sort by lowest score / orphan penalty, fix those first.
• ## See Also is bidirectional — if A links B, B links A.
• Use standard markdown links only — NEVER wikilinks ([[...]]). An OKF consumer follows markdown links; it cannot follow [[...]]. If you find a [[...]] link while gardening, convert it. Same-topic link: [Refund SLA](./refund-sla-and-escalation.md). Cross-topic link: [OAuth setup](../auth/oauth-setup.md). Why: the protocol's relative-link convention; ./ is same-topic, ../ crosses one topic boundary, matching the one-level layout. See ../harness/references/wiki-protocol.md "## Conventions".
• When you add a genuinely new top-level subject, make sure wiki/index.md references it so the map stays complete.

Prune — archive, retire, arbitrate, compact

Prune is archival, never rm. A superseded article moves to wiki/<topic>/_archive/<article>__YYYY-MM-DD.md; you do not delete it. Why: the safety rails forbid destructive loss, and _archive/ is gitignored from compaction so it stays out of the way without vanishing.

• Conflicts: you flag contradictions and the human arbitrates. Once they choose a winner, you may apply the resolution and annotate the loser — but you never auto-pick. Why: silently choosing a side is data corruption.
• Stale answers: mark a page or archived copy with a > ⚠ Stale — superseded YYYY-MM-DD note rather than rewriting history.
• Compaction is bounded: only [FILLED YYYY-MM-DD] gaps older than 90 days may be compacted, and only via a single marker prepended to log.md — a gap gets a [FILLED] stamp, never a deletion.
• Log every prune by prepending to wiki/log.md.

A full worked prune session (stale + superseded + conflict + gap compaction, all logged) is in references/gardening-playbook.md.

Safety rails

Inherited from ../harness/references/wiki-protocol.md — do not override them; each one guards against a loss you cannot undo.

1. Preserve before overwrite. Never overwrite an article without first copying the old version to wiki/<topic>/_archive/<article>__YYYY-MM-DD.md.
2. Never auto-resolve a conflict. Flag it; the human arbitrates.
3. The reserved files only grow. Log every change in wiki/log.md, the OKF reserved change-log: new entries are prepended at the top (newest first), ISO 8601 dates. gaps.md is the append-only one — new entries go at the bottom. Past entries in either are immutable: a gap gets a [FILLED YYYY-MM-DD] stamp, nothing is ever edited out or deleted.
4. Never touch an article whose timestamp is < 24h ago without explicit user say-so. Why: it is likely still being worked. (timestamp is the OKF last-meaningful-edit field, ISO 8601 — see ../harness/references/wiki-protocol.md "## Conventions".)

Anti-patterns

Hand-offs

Route elsewhere when the request is not gardening an existing wiki: