Ingest source

Type: kb/types/instruction.md

Ingest one source into a kb/sources/*.ingest.md report. The source may be a URL or an existing Markdown snapshot under kb/sources/.

Contract

Target: $ARGUMENTS

The direct output is the .ingest.md report next to the source snapshot. URL snapshotting and connection discovery may write their own delegated artifacts. Do not directly write any other library artifacts.

Interpret "our" through the installed KB's goals and local collection contracts. In this repository, "our" means agent-operated KB methodology. In another installed KB, it means that project's declared system, work, codebase, policy, product, or domain.

Read and follow kb/sources/types/ingest-report.md before drafting the report. If this skill and the type spec conflict about report content, the type spec wins.

Steps

  1. Resolve the target.
  2. If $ARGUMENTS is empty, list recent kb/sources/*.md files excluding .json and .ingest.md, then ask which one to ingest.
  3. If the target starts with http:// or https://, invoke cp-skill-snapshot-web on the URL. Parse the Snapshot saved: line from its output; that path is the source snapshot for the next step.

  4. Otherwise, treat the target as the source snapshot path.

  5. Run connection discovery. Invoke cp-skill-connect on the source snapshot path. Wait for it to finish. For source snapshots, read kb/reports/connect/sources/<snapshot-name>.connect.md.

  6. Extract connection context. From the generated connect report, note:

  7. Which existing artifacts were identified as connections
  8. What relationship types were found
  9. Any synthesis opportunities or tensions flagged

Treat Maintenance Observations as non-actionable context: mention durable signals in the ingest report only when relevant, and do not act on or promote them during ingest.

The connect report is generated, gitignored working context. Do not cite it, link to it, or name its path in the durable ingest report. Summarize its findings and link only durable KB artifacts or source snapshots.

Distill, do not transcribe: connect casts a wide candidate net by design. Drop weak, speculative, or duplicate edges and keep only settled, durable judgments about this source's role. Write Connections Found as compact prose naming that role (for example: anchor, technical basis, counterpoint, legal disposition, public statement, limitation) rather than an inventory of every candidate connect surfaced.

If no casebook notes exist yet for the target collection, say so plainly and stop there. Do not substitute a full map of this source's relationships to other already-captured sources, and do not frame the section as prospective connections for notes that do not exist yet — that framing goes stale the moment notes are written, and re-deriving those relationships is connect's job to do then, not the ingest's job to pre-write now. A single relationship that bears on this source's likely role is enough.

  1. Draft the ingest report. Write the analysis as an ingest-report, using the source snapshot and the connection context. The report must classify the source, summarize it, explain how it connects to the current KB, extract goal-relative value, state limitations, and recommend one advisory next action.

If the source is not relevant to this KB, say so in the report. Keep the report short, explain the mismatch, and recommend no promotion or source-only filing as appropriate.

  1. Save the report next to the snapshot.
  2. Input: kb/sources/some-article.md

  3. Output: kb/sources/some-article.ingest.md

  4. Validate. Run:

bash commonplace-validate kb/sources/some-article.ingest.md

If this run created or edited the source snapshot, validate that snapshot too. Fix validation failures in files this skill is allowed to write before stopping.

  1. Report the result. Tell the user where the ingest report was saved and state the recommended next action.

Constraints

  • Run cp-skill-connect before classification or value extraction.
  • Write only the .ingest.md report directly.
  • Base extractable value on what is new relative to the discovered connection context.
  • Include effort tags on extractable value items.
  • Recommend exactly one advisory next action.