[ OPERATIONS · OPERATOR UTILITY ]

/knowledge-ingest

Before doing anything else, read these two files **in full**:

Download the skill file (.md)

Knowledge Ingest — ACME Agency

Triggers

• Automatic: fired by ACME Agency/scripts/lib/knowledge_inbox.mjs as a detached claude -p '/knowledge-ingest' subprocess when the inbox reaches 10 unprocessed items.
• Manual: user runs /knowledge-ingest to force a pass (useful for sanity-checking after the first few captures, or to catch up if the threshold hasn't been hit in a while).

Critical pre-reads

Before doing anything else, read these two files in full:

1. ACME Agency/knowledge/KNOWLEDGE.md — the schema. All rules for page creation, frontmatter, bootstrap conservatism, contradiction handling, and citation format live there. This skill is a thin executor; the schema is the source of truth.
2. ACME Agency/knowledge/wiki/index.md — what pages already exist. Required so you know whether to create a new page or update an existing one.

If either file is missing, stop immediately and tell the user the wiki is not set up.

Workflow

Step 1 — Lock check

Check ACME Agency/knowledge/.ingest.lock.

• If the file exists and its mtime is less than 30 minutes old, exit immediately with the message Another ingest is in progress (lock is <age> old). Skipping.. Do not write anything. Do not touch the inbox.
• If the lock exists but is older than 30 minutes, overwrite it (assume the previous run crashed).
• If no lock exists, create it. Write the current ISO timestamp into the file.

Step 2 — List unprocessed inbox items

Use Glob on ACME Agency/knowledge/raw/inbox/*.md.

• If empty: delete the lock file and exit with Inbox is empty — nothing to ingest.
• Otherwise: read each file to confirm frontmatter ingested: false. Collect a list of items with { path, client, client_slug, vertical, market, analysis_type, date, source_data }.

Hard cap: do not process more than 30 items in a single pass. If the inbox has more than 30, process the 30 oldest (by filename date prefix) and leave the rest for the next run.

Step 3 — Group and plan

Group the batch by:

• Client (always) — every item produces an entry in the client's running notes page.
• Vertical (maybe) — only groups of ≥3 different clients per vertical qualify for a verticals/ page this pass.
• Tactic (maybe) — only recurring patterns (≥2 clients, same concrete tactic) qualify for a tactics/ page.
• Concept (rarely) — only principles surfaced independently by ≥2 clients qualify for a concepts/ page.

Apply the bootstrap rules in KNOWLEDGE.md §"Bootstrap rules" strictly. Under-structure, don't over-structure. When in doubt, only touch wiki/clients/<slug>.md and nothing else.

Produce a short plan and print it to stdout before writing anything:

Ingest plan:
  - 10 inbox items from 4 clients
  - Touching: clients/ACME Agency.md (new), clients/ACME Agency.md (update), clients/ACME Agency.md (new), clients/ACME Agency.md (update)
  - Vertical page eligible: none yet (construction has 1 client, dental has 1, medical has 1, logistics has 1)
  - Tactics pages eligible: none yet
  - Concepts pages eligible: none yet

Step 4 — Write/update pages

For each page you decided to touch:

wiki/clients/<client-slug>.md (always):

• If the page does not exist, create it with a short header:

```markdown # <Client Name>

Vertical: <vertical> Market: <market> Client folder: ACME Agency/clients/<folder>/

## Running notes

_Chronological findings from analyses. Newest at top._ ```

• Prepend a dated entry for each inbox item that belongs to this client:

```markdown ### [2026-04-08] google-ads-optimize

• <key finding 1>
• <key finding 2>
• <key finding 3 — include numbers, comparisons, specific campaign/ad/term names>

(source: raw/archive/2026-04/2026-04-08_ACME <id>.md) ```

• Compress hard. 3-7 bullets per entry. No raw data dumps. No recaps of obvious metrics. Focus on what's non-obvious, recurring, or actionable.

wiki/verticals/<vertical>.md (only if qualified):

• If the page doesn't exist, create with header + "## Patterns" section.
• Append or update patterns you can justify from the batch + prior wiki data combined. Cite sources inline.
• Flag contradictions with the > **Contradiction [date]:** ... callout format from the schema.

wiki/tactics/<platform>/<topic>.md (only if qualified):

• Same rules. Focus on replicable patterns with evidence.

wiki/concepts/<concept>.md (only if qualified):

• Same rules. A concept page should define the concept, cite supporting examples, and link out to the client/vertical/tactic pages that reference it.

Step 5 — Update index.md

Open wiki/index.md. For every page you created or updated in Step 4, add or update its line in the appropriate section (Clients / Verticals / Tactics / Concepts). Format:

- [<Page Title>](<relative/path.md>) — <one-line summary>

Keep summaries tight (under 120 chars). Remove the "no pages yet" placeholder text from any section that now has entries.

Step 6 — Append to log.md

Append a single line to wiki/log.md using the parseable prefix:

## [2026-04-08] ingest | 10 items | touched: clients/ACME Agency.md, clients/ACME Agency.md, clients/ACME Agency.md, clients/ACME Agency.md

Include an optional second line for context if useful:

  batch: 4 clients, 0 verticals, 0 tactics, 0 concepts | notes: first real ingest

Step 7 — Archive processed inbox items

For each inbox item you processed:

1. Rewrite its frontmatter to set ingested: true (leave the rest of the file unchanged).
2. Move the file from raw/inbox/ to raw/archive/<YYYY-MM>/ (create the month folder if needed). The filename stays the same.

If you intentionally skipped an item (e.g., malformed, missing required frontmatter), leave it in the inbox and mention it in the log.

Step 8 — Release lock

Delete ACME Agency/knowledge/.ingest.lock.

Step 9 — Final summary

Print a short summary to stdout (this may end up in a detached subprocess log, but still useful):

Ingest complete.
- Processed: 10 items from 4 clients
- Pages touched: 4 client pages, 0 verticals, 0 tactics, 0 concepts
- Inbox remaining: 0
- Archived to: raw/archive/2026-04/

Do not post to Slack. Do not notify Faris. This skill is meant to be silent background maintenance — its output is the wiki, not a report.

Hard rules

1. Never invent data. If a claim is not supported by an inbox item or an existing wiki page, do not write it.
2. Never cite a client not in the current batch or prior wiki. No hypothetical examples.
3. Never delete old wiki content. Appending, updating, and flagging contradictions are fine. Deletion is for the lint pass only.
4. Never skip the schema pre-read. The bootstrap rules change over time; always reload them from KNOWLEDGE.md.
5. Never touch non-wiki files. This skill does not edit client folders, scripts, CLAUDE.md, or anything else. Only knowledge/wiki/ and knowledge/raw/.
6. Never run more than one ingest at a time. Respect the lock.
7. Never post to Slack or notify the user. Silent background maintenance.
8. Never summarize the ingest to the user in this session's main conversation if invoked from the Task tool. Return a compact confirmation only.

Error handling

• If the inbox is empty: exit cleanly with Inbox is empty — nothing to ingest. and release the lock.
• If KNOWLEDGE.md is missing: exit with Wiki not set up — KNOWLEDGE.md missing. Do not create anything.
• If an inbox item has malformed frontmatter: skip it, log the skip, continue with the rest.
• If a page write fails: roll back (do not move the inbox item to archive), release the lock, exit with an error. The next run will retry.
• If you encounter any state you don't understand (orphan lock, partially-archived item, index.md in unexpected shape): stop, do not write, release the lock, and exit with a clear description of what you saw. Faris can run /knowledge-ingest manually after investigating.

Quality bar

A good ingest:

• Produces 1-3 new/updated pages per batch on average in bootstrap phase.
• Every new wiki claim has a source citation.
• Client running notes read like a dated journal, not a data dump.
• The index.md stays under 200 lines and scannable.

A bad ingest:

• Creates vertical pages from a single client.
• Copies raw JSON or full tables into wiki pages.
• Overwrites prior insights instead of appending or flagging contradictions.
• Skips the lock or the archive step.
• Prints the whole wiki back to stdout.