ctx-kb-ingest

name	ctx-kb-ingest
description	Editorial knowledge-ingestion pass. Reads sources the user supplies, declares its pass-mode (topic-page / triage / evidence-only) before extraction, and is held to mode-specific completion semantics. The topic page is the deliverable; the closeout is the audit trail.
allowed-tools	Bash(ctx:*), Bash(ls:*), Bash(git status), Read, Edit, Write

Editorial Ingestion Pass

This skill is the single editorial pass for adding knowledge to .context/kb/. It reads materials the user supplies, decides which topic page(s) they belong to, finds-or-creates those pages, writes synthesized prose section by section, mints EV-### rows in the structured layer as it cites them, cross-links neighboring topics, updates the source-coverage ledger, and writes a closeout file under .context/ingest/closeouts/.

The split between "extract claims" and "write the topic page" is mechanical, not editorial. A student reading a book does not extract a glossary first and synthesize later, they read and write at the same time. This skill matches that model: the user supplies intent and material; the skill does judgment and typing.

The topic page is the deliverable. The closeout is the audit trail. The closeout never substitutes for the page. Intermediate artifacts (EV rows, glossary entries, candidate-source registries, closeouts) are valuable, but they do not validate topic-page work by themselves; only the topic page does.

Authoritative background reading lives at .context/ingest/KB-RULES.md and specs/kb-editorial-pipeline.md. This skill encodes the workflow contract; the rules file is the constitution. Hand-edit KB-RULES.md to evolve the contract; do not paraphrase it here.

When to Use

• The user supplies one or more sources (paths, URLs, MCP resources, inline natural-language descriptions) and wants them read into the kb.
• The user says "ingest the transcripts", "pull this into the kb", "add evidence from ", "extract claims from this call", or invokes the explicit slash form with paths.
• A prior pass left residue (a topic-page-drafted ledger row, a Next pass hint in a closeout) and the user is resuming.

When NOT to Use

• The user asked a question about the kb (use /ctx-kb-ask).
• The user wants a structural audit of the kb (use /ctx-kb-site-review).
• The user wants to re-ground existing kb claims against external sources (use /ctx-kb-ground).
• The user wants to park a quick finding for the next ingest (use /ctx-kb-note).
• No sources were supplied (refuse-on-empty; see §Refuse-on-empty below).
• .context/kb/ does not exist (refuse with the no-pipeline message in §Pre-write gates).

Authority Boundary (vs Other Skills)

• /ctx-kb-ingest: primary editorial pass. Reads materials (in-tree paths, out-of-tree paths, URLs, MCP resources, inline references); writes topic pages (.context/kb/topics/<slug>/index.md, plus optional sibling sub-pages); mints evidence, glossary, source-map, timeline, contradictions, outstanding questions; cross-links into existing kb topology; updates the source-coverage ledger; writes closeout. Topic-page file creation is performed only by ctx kb topic new: this skill MAY invoke that CLI as part of a topic-page pass, but it MUST NOT synthesize or write a scaffold directly. This preserves the public editorial workflow (/ctx-kb-ingest) and the actual scaffold authority (ctx kb topic new) as two separate facts.
• /ctx-kb-ask: Q&A grounded in the kb. Read-only on prose; refuses to web-jump; flags gaps the kb cannot answer.
• /ctx-kb-site-review: structural audit; mechanical fixes only. Defers anything that requires evidence judgment.
• /ctx-kb-ground: external grounding against grounding-sources.md; advances ledger rows for sources it refreshes.
• /ctx-kb-note: lightweight capture into .context/ingest/findings.md; never writes to a topic page or to evidence-index.md.

This skill writes prose AND evidence rows AND scaffold (via CLI) AND cross-links AND ledger updates in the same pass; that combination is unique to ingest.

Usage Examples

/ctx-kb-ingest ./inputs/2026-04-12-call.md "cursor hooks"
/ctx-kb-ingest ./inputs/your-domain/
/ctx-kb-ingest https://cursor.com/docs/hooks
/ctx-kb-ingest ./a.md ./b.md "incident retros"
/ctx-kb-ingest --inline "the four transcripts under inputs/ \
  and the pool.go file" "connection pooling"

Input Contract

Sources, supplied as one or more of:

• Paths: folder to recurse, single file, list of files.
• URLs: primary-source web pages.
• MCP resources: named resources from connected MCP servers.
• Inline gestures: natural-language naming the materials.
• Open invitation: "feel free to search for more". The skill gets web-search and MCP-discovery authority for this pass; hard cap of 50 total sources.

Optional second argument, topic name, e.g. "cursor hooks". When omitted, the skill proposes one at §3 of Process and confirms with the user before any extraction work. Naming the topic up front skips that round-trip.

Refuse-on-Empty

The skill writes to the kb; refuse-on-empty is the default. If the invocation supplied no sources and no inline gesture, return exactly:

no sources provided; pass a folder, a URL, an MCP resource, or describe the materials inline.

Stop. Do not prompt for sources interactively, do not invent a topic, do not propose a triage pass on imagined material. The CLI enforces this independently via cmd/ingest.

Pre-Write Gates

Three distinct refusals, each leaves zero residue (no INBOX.md rewrite, no SESSION_LOG.md entry, no claim extraction, no ledger update, no closeout, no topic-page edits):

• .context/ missing entirely → suggest ctx init and stop.

• .context/ingest/ missing (project initialised before this spec shipped) → suggest ctx init --upgrade and stop.

• Kb scope undeclared (.context/kb/index.md missing, contains the TODO: declare what this kb covers placeholder, has no ## Scope H2, or ## Scope lacks substantive non-placeholder prose):

  kb scope is undeclared. Open .context/kb/index.md and replace the TODO placeholder with a one-paragraph scope statement that names what is in scope and what is out. /ctx-kb-ingest refuses to ingest until scope is declared.

Pass-Mode Contract

Every invocation MUST classify itself as exactly one of three modes before any source extraction begins. The mode commits the pass to a specific definition of done; the skill is held to that definition and may not narrate success on residue belonging to a different mode. Full mode semantics live in .context/ingest/KB-RULES.md §Pass-mode contract.

Mode	Mints prose?	Mints EV-###?	Touches topic page?	Default?
topic-page	yes	yes	yes (create/extend)	yes
triage	no	no	no	no
evidence-only	no	yes (tagged)	no	no

Mode selection rules. Default is topic-page. triage fires only when the user supplied multiple disparate sources with no clear single topic, OR explicitly invoked triage language. evidence-only fires only on explicit user request matching the valid-trigger criteria ("just mint EV rows", "backfill evidence"); the skill MAY NOT infer it from source size, ambiguity, time pressure, or operator convenience.

Up-front declaration (mandatory). Before extraction begins (after pre-write gates pass and before topic resolution), emit a visible pre-work declaration in the response stream:

Pass-mode: <mode> Reason: <one sentence; required when non-default> Definition of done: <mode-specific completion criterion>

The declaration is a contract, not a label. The skill is bound to it for the rest of the pass.

Mid-pass mode-switching is forbidden. If the work in flight no longer fits, abort with a partial closeout citing what was done, and recommend re-invocation under the correct mode. Silent mode-drift is a hard anti-pattern.

Topic-Page Circuit Breaker

A pass operating in topic-page mode MAY NOT report topic-page: produced or topic-page: extended unless ALL of the following are true at completion:

1. .context/kb/topics/<slug>/index.md (or a sibling sub-page like .context/kb/topics/<slug>/<sub>.md) exists and was created or extended in this pass.
2. The page cites at least one EV-### row that resolves to evidence-index.md.
3. ctx kb site build ran clean (or its failure is named in the closeout's Next pass hint AND the pass reports topic-page: deferred).
4. The cold-reader orientation rubric records Result: pass in the closeout's What changed section. All four rubric items must be yes.

Any failure → topic-page: deferred and the source-coverage ledger advances to topic-page-drafted (not comprehensive). This invariant prevents intermediate residue from being treated as topic-page success. Topic-page validation requires the topic page.

Source-Coverage Ledger

.context/kb/source-coverage.md is a state machine over every source the kb has touched. Allowed transitions live in KB-RULES.md §Source-coverage ledger; do not paraphrase them here. Every pass updates the ledger before writing the closeout. Lying to the ledger is a hard anti-pattern. Set the state honestly even when it means recording incomplete work.

Cold-Reader Orientation Rubric

Four yes/no items recorded in the closeout's What changed section, in topic-page mode:

Cold-reader orientation:
- Concept clear?                yes|no: <short note>
- Why this kb cares clear?      yes|no: <short note>
- Canonical evidence reachable? yes|no: <short note>
- Boundaries clear?             yes|no: <short note>
Result: pass | fail

Result: pass requires all four yes. Any no → Result: fail → circuit-breaker fails → topic-page: deferred.

Life-Stage Check

Count .context/kb/topics/*/index.md pages before this pass begins synthesizing:

• < 5 topic pages → bootstrap mode. Skip reconciliation ceremony; synthesize topic pages aggressively. Exception: surface a contradiction even in bootstrap if the new material plainly contradicts existing kb claims.
• >= 5 topic pages → maintenance mode. Apply full reconciliation discipline (laddering, demotion, contradiction detection).

Document the life-stage call in the closeout's frontmatter (life-stage:) and What changed section.

Process

1. Verify pre-write gates. Refuse cleanly with the matching message from §Pre-write gates if .context/, .context/ingest/, or kb scope is missing. No residue on refusal.

2. Declare pass-mode and surface the up-front declaration. Determine the mode per §Pass-mode contract. Emit the three-line declaration block in the response stream before any further work. Mid-pass mode-switching is forbidden; abort and re-invoke if the work no longer fits.

3. Resolve the topic. (Topic-page mode only; skipped in triage and evidence-only.)

   • Read .context/kb/source-coverage.md in full first. It answers "what does this kb already know about which sources, and at what completeness?": a precondition for honest topic resolution, not an afterthought.

   • Topic-adjacency pre-flight (mandatory). Scan the ledger for rows whose state is not in {comprehensive, skipped, superseded} AND whose Topic is plausibly adjacent. Heuristics:

     • Shared first segment of a slash- or hyphen-separated slug: cursor/skills is adjacent to cursor/hooks.
     • Shared product / vendor / surface in the source URL or description.
     • Explicit cross-references in the named topic's existing sub-pages or this pass's source set.

     For each adjacent incomplete topic surfaced, this pass MUST:

     1. Acknowledge it in ## Related concepts in this kb on the topic page being authored.
     2. Surface it in the closeout's Adjacency pre-flight block.
     3. Surface it in the response contract's Adjacent topics noted field.

     Do NOT enumerate EV-### IDs by name in the adjacency block. Use count + location ("seventeen rows in evidence-index.md"). Naming an EV row from a lower-confidence sibling demotes the floor of cited bands.

     Silence is not a clean pre-flight; if zero matches, record "no incomplete adjacent topics surfaced" explicitly.

   • Named vs unnamed branches. If the user named a topic, accept it and map to slug (lowercase + kebab-case). If not, scan the inputs to propose one and confirm:

Edge Cases

Case	Expected behavior
Empty input	Refuse with the standard no-sources text. No residue.
.context/ missing	Refuse; suggest ctx init. No residue.
.context/ingest/ missing	Refuse; suggest ctx init --upgrade. No residue.
Kb scope undeclared	Refuse with the scope message; point at .context/kb/index.md. No residue.
Source returns nothing usable (404, binary, paywall)	Record in closeout's Next pass hint AND the topic page's "Open questions"; advance the ledger row to skipped with the failure reason. Do not invent claims.
All sources skipped during admission	Write a short closeout with empty Topic(s) touched and What changed; Next pass hint lists every skipped source with scope-citation.
Material spans 3+ topics and user can't decide	Ask once in §3; if still unresolved, abort with a partial closeout recommending re-invocation under triage.
Discovery turns up zero additional sources	Note in closeout's Inputs section. Not a failure.
Stale Status block on existing page	Flag in closeout's Next pass hint; do not silently overwrite the verification cursor unless the source was actually re-verified.
Multiple sessions filling the same page	Read existing prose first; do not overwrite human edits; append/extend rather than replace.
Page scaffolded long ago with older template	Fill what's there; do not reformat to match a newer template. Open a task if drift is significant.
ctx kb topic new fails or refuses (slug exists, kb missing)	Resolve the underlying condition and retry; do not hand-write a scaffold.
ctx kb site build fails during §12	Report topic-page: deferred; name the build failure in Next pass hint; ledger to topic-page-drafted (NOT comprehensive).
Cold-reader rubric returns

Hard Anti-Patterns

• Treating closeout existence as topic-page validation.
• Skipping the topic-page circuit breaker in topic-page mode.
• Inferring evidence-only from source size, complexity, ambiguity, time pressure, or operator convenience.
• Mid-pass mode-switching (abort and re-invoke instead).
• Hiding incomplete coverage under a comprehensive-looking closeout (lying to the ledger).
• Skipping the topic-adjacency pre-flight, or running it but failing to acknowledge surfaced incomplete adjacent topics.
• Claiming topic-page: produced when the cold-reader orientation result is missing.
• Asking the human mid-pass beyond the §3 naming gate, unless continuing would change durable kb topology, evidence confidence, source admission, or scope.
• Inventing claims beyond what the source backs.
• Inventing EV-### citations to make a page look complete.
• Promoting claims above speculative without an evidence-index.md row.
• Promoting a topic page above its weakest cited band.
• Setting Confidence above speculative while any TBD-cite remains.
• Setting Author: hand-authored on agent-ingested prose.
• Re-extracting from a source that already has EV-### rows instead of reusing the IDs.
• Citing an evidence-only-tagged row in a topic page without re-reading the source first.
• Renumbering or deleting EV-### rows when reconciling.
• Skipping the closeout once the pass clears pre-write gates.
• Bypassing ctx kb topic new when scaffolding a page.
• Running maintenance discipline against a bootstrap-stage kb.
• Hand-editing INBOX.md.

Output Contract

For pre-write refusals, return only the specified refusal text and stop. No closeout, no residue.

For passes that clear pre-write gates, emit the up-front declaration first (between §1 and §3):

Pass-mode: <mode> Reason: <one sentence; required when non-default> Definition of done: <mode-specific criterion>

Then proceed. At completion, end with this structured summary:

• Pass-mode: as declared, with reason if non-default.
• Topic-page: produced [<slug>], extended [<slug>], deferred (<reason>), or not-applicable (triage / evidence-only).
• Validation: passed, not-attempted, or deferred (<reason>).
• Coverage: current state(s) from source-coverage.md for sources touched.
• EV range minted: e.g. EV-035..EV-051, or none.
• Counts: glossary entries added, source-map rows added, cross-links written, contradictions surfaced, questions opened.
• Life-stage: bootstrap or maintenance, with the topic-page count it was based on.
• Closeout: filename on its own line.
• Adjacent topics noted (topic-page mode only; mandatory): either none surfaced or a slug-list with states. Free prose fails validation; the doctor advisory parses this field.
• Next-recommended-action: explicit invocation that would resume incomplete work. Adjacent topics surfaced by the pre-flight MUST appear here too (deliberate redundancy).
• Review-required: true for evidence-only passes; otherwise omit.

The structured summary, the closeout's body, and the source-coverage ledger MUST agree. Discrepancies between the three are a hard anti-pattern; the doctor advisory detects them and surfaces a non-fatal warning on next ctx doctor run.

Quality Checklist

Before reporting completion, verify:

• Pre-write gates passed (or the matching refusal was returned with zero residue).
• Pass-mode declaration was emitted in the response stream before any extraction.
• Source-coverage ledger advanced honestly for every source touched.
• Topic-adjacency pre-flight ran in topic-page mode and its result is in the closeout AND the page AND the response contract.
• Cold-reader rubric is recorded in topic-page mode.
• Circuit-breaker check ran in topic-page mode; failure → topic-page: deferred, NOT produced.
• Closeout written with all required frontmatter fields (sha, branch, mode, pass-mode, life-stage, generated-at).
• Structured response summary matches the closeout body and the ledger.