Skip to content

ericrisco/rsc-harness / skills/knowledge-ops

knowledge-ops

Unverified

Use when an already-running 02-DOCS/ wiki needs gardening judgment — what is worth capturing (default: nothing), where a loose note belongs, whether to split a bloated article or merge near-duplicates, how to link orphans back in, and what retires to _archive (never delete). NOT building or sweeping the wiki engine itself (that is `harness`).

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 for technical_level, which sets your register (technical terms, or plain words with analogies). Why: a non-technical owner needs each decision explained with an analogy; a technical one reads the term directly. Either way, speak in the orient voice: short, and every answer understandable on its own.
  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.

OperationYou are doing this when…Primary signalWrites to
CaptureA note/source needs a decision: keep, where, at what altitudenew content in inbox//raw/ or a loose user noteraw/ and/or wiki/<topic>/<article>.md
StructureAn article is bloated, mistitled, or duplicatedlength, a non-singular Overview, near-duplicate titleswiki/<topic>/, _archive/
LinkPages are unreachable or under-connectedscores.json orphan_penalty (=5), low inbound count## See Also in articles, index.md
PruneAnswers are stale, articles superseded, conflicts unresolved, gaps bloatedfreshness, conflict annotations, old [FILLED] gaps_archive/, log.md, gaps.md

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

Anti-patternWhy it is wrongDo instead
Capturing everything "to be safe"The wiki rots into a dump; the model stops being a modelRaise the bar; default to discard or raw/-only
rm-ing a superseded articleLoses history the rails protectArchive to _archive/<article>__YYYY-MM-DD.md
Auto-picking a winner in a contradictionSilent data corruption; you guessedFlag it; let the human arbitrate
Re-running harness to fix a broken linkWrong tool — the Maintenance Pass already auto-fixes linksRepair ## See Also by hand; let automation handle the rest
Nesting wiki/a/b/c.mdBreaks the one-level topic ruleFlatten to wiki/<topic>/<article>.md
Editing a past log.md / gaps.md entryBreaks the immutable audit trailAdd a new entry — prepend to log.md (newest first), append to gaps.md
Splitting on length aloneTwo halves of one thesis are worse than one pageSplit on thesis count, not line count
Creating a new topic for a one-off noteTopic sprawl; reuse beats createFile under the nearest existing topic

Hand-offs

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

RequestRoute to
Build/bootstrap the wiki, run an inbox sweep, scaffold 01-TOOLS, generate root CLAUDE.mdharness (../harness/SKILL.md) — it owns the engine
Turn a meeting transcript into a recap with action items + ownersmeeting-notes (../meeting-notes/SKILL.md)
Author a decision record (ADR) with alternatives, status, review cadencedecision-records (../decision-records/SKILL.md) — you may file one; that skill authors the discipline
Document a repeatable procedure step by stepsop-builder (../sop-builder/SKILL.md)
First-pass walkthrough of an unfamiliar codebasecodebase-onboarding (../codebase-onboarding/SKILL.md)
Run a literature / source-gathering research projectresearch-ops (../research-ops/SKILL.md)
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall