wiki-ingest git:20260917.b0c9c00A

Immutable. This exact content is served forever at /api/v1/blob/5aa5b567cad30cd0.

---
name: wiki-ingest
effort: medium
argument-hint: "[the lesson or edge case]"
description: Add one verified lesson or edge case to the bundled wiki. Route it to the right domain and category, merge into an existing page before creating a new one, and enforce sourcing and positive-guidance rules. Use when capturing a documented best practice or a production edge case.
---

# Ingest

> **In the dev-loop plugin.** The wiki lives at the plugin root. When you run this
> skill by hand for reference, read paths (`INDEX.md`, `wiki/`, `templates/`,
> `AGENTS.md`) against **`${CLAUDE_PLUGIN_ROOT}/`**. When this skill is driven by
> **`knowledge-flush`** to open a PR, that skill first prepares a **writable git
> checkout of the dev-loop repo** and passes you its path as `<wiki_root>` — do all
> reading and writing there (never edit the installed plugin dir, which is
> read-only and untracked). `knowledge-flush` handles the branch/commit/PR after
> you finish; your job is only the routed, sourced edit + plumbing update.

Input: one unit of knowledge. Either a source (doc, article, post-mortem, benchmark)
or a distilled lesson ("we hit X; doing Y fixed it because Z").

## Steps

1. **Extract the case.** State the knowledge as: *trigger situation → directive →
   why → evidence*. If you cannot fill "trigger situation" precisely, stop: ask the
   contributor what situation makes this advice apply. Knowledge without a trigger
   cannot be routed and pollutes context.

2. **Convert prohibitions.** If the input arrives as "never do X" / "avoid X",
   rewrite it as the replacement action: "when <situation that tempts X>, do Y".
   Keep the prohibition only as an `Instead of` row paired with Y.

3. **Route.** **Layer first.** The knowledge is project-specific when its
   directive names this repository's own files, modules, services, conventions
   or infrastructure, or would be wrong in another codebase; route
   project-specific knowledge to `wiki-local/<domain>/<category>/<slug>.md` in
   that project (same `templates/page.md`, id `local-<domain>-<category>-<slug>`,
   one row in `wiki-local/index.md`) and general knowledge to the bundled wiki.
   Then match the case to a domain via `INDEX.md`, then to a category via the
   domain `index.md`. If no category fits, create one (update the domain index) —
   but first re-check that an existing category doesn't already cover it under a
   different name.

4. **Merge before creating.** Read every existing page in the target category whose
   "load when" line overlaps the new case.
   - Semantic dedupe first: call the dev-loop-wiki tool `wiki_search` with the
     candidate's trigger sentence (k=5), open each hit's page and read its
     "When this applies"; the first trigger that describes the same situation
     is the merge target for the bullets below, and the top-5 hits are listed
     in the step-8 report. When the `wiki_search` tool is absent from the
     session or returns an empty list, continue exactly as this step read
     before the tool existed.
   - Same trigger, same directive → add the new source / edge case to that page.
   - Same trigger, conflicting directive → do NOT overwrite. Add the conflict to the
     page under `Edge cases` if it is condition-dependent, or flag it in `log.md` as
     `contradiction` for the owner to resolve.
   - Same trigger, existing page wrong as a whole (its directive is refuted by the new source, not merely condition-dependent) → create the new page, then on the old page set `status: superseded` and `superseded_by: <new page id>`, move its domain `index.md` row to the new page, keep the old file on disk, and append `## [YYYY-MM-DD] revise | <old id> superseded by <new id> — <why>` to `log.md`. A page whose premise is gone with no replacement gets `status: retired`, the reason in its body, and the same delisting.
   - New trigger → create a new page from `templates/page.md`.

5. **Source it.** Fill `sources:` with real, checkable citations. Do not invent or
   approximate URLs — an unverifiable citation is worse than none. If the only
   evidence is experience, set `confidence: field-tested` and describe the context
   in the page body. If there is no evidence yet, set `confidence: unverified`.

6. **Respect the format.** Template sections, ≤120 body lines, decision tables for
   branches, no vague qualifiers in directives (see `AGENTS.md`).

7. **Update the plumbing.** Domain `index.md` gets the page with an accurate
   "load when" line. `log.md` gets `## [YYYY-MM-DD] ingest | <page id> — <one line>`.
   Add `related:` links both ways for genuinely adjacent pages.

8. **Report.** List pages created/updated, conflicts flagged, and anything left
   `unverified` that needs evidence, and the top-5 wiki_search hits considered in step 4.