skills/skills/consume/SKILL.md

---
name: consume
description: Consume a project (or, later, another source) into the agent's personal wiki — distil generalized, transferable knowledge from it into the Obsidian vault's agent-owned area, then clear the consumed scaffolding. Deliberate: run as /consume [target], never automatically.
disable-model-invocation: true
---

# consume

Mine a source for its knowledge, routing each fact to the agent's own wiki or the target's always-loaded docs, then clear the consumed scaffolding once the knowledge is safely captured.

`/consume [target]` ingests one target — a filesystem path, defaulting to the current directory — and distils what it mines into two channels.
It is the write side of a pair with the read-only `/wiki`, which it invokes to read the rest of the vault.

The **pull channel** is the wiki — reusable knowledge a future agent retrieves on demand — and a fact earns a note there only if it both **generalizes** past the target it came from and is **trigger-able**, meaning some symptom, error, or task would send that agent looking for it.
The **push channel** is the target's own always-loaded documentation, its `CLAUDE.md`, which carries what is useful but not wiki-shaped: a concrete repo-specific answer, or a proactive rule whose value is firing unprompted.
A single fact mined from the source usually splits across both — the transferable general lesson to the pull channel, the specific residue it leaves behind to the push channel.

Nothing is written and nothing is deleted until the user approves the plan.

## The write surfaces

Consume writes to two places and nowhere else.

The vault lives at `$(xdg-user-dir DOCUMENTS)/notes`.
Resolve it, and if it does not exist report that the vault is unreachable and stop.
Inside the vault, write only under `01 sources/claude/`, treating every other vault path as off-limits to writes.
Outside the vault, the only sanctioned write is the target's own always-loaded documentation, its `CLAUDE.md` — the push channel of step 6.
Everything else in the target is read-only, save for the scaffolding step 7 deletes.

The harness does not apply the vault's own permission rules when you run from outside it, so enforcing the vault boundary is the skill's job.
All reading of the wider vault goes through `/wiki` (step 3), which enforces the vault's read boundary itself.

## 1. Select the branch

Route the target through this ladder, first match wins:

- A directory containing `.claude/spec/` and/or `.claude/tasks/` → a project: follow [`project.md`](project.md).
- No rung matches → report that the target is not something consume knows how to read, write nothing, and stop.

Done when a branch file is selected, or consume has stopped on an unsupported target.

## 2. Read the target and establish ground truth

Follow the selected branch file to understand the target's *current* state.
The branch file names its source of truth and what within the target is merely stale intent; ground your understanding in the former, never the latter.

Done when you understand what the target actually is now, from its branch's source of truth.

## 3. Read what the wiki already knows

Two reads with different jobs:

- Invoke `/wiki` on the concepts the target raised, to learn what the whole vault already holds — so new notes link to existing notes and hubs, and you do not re-capture knowledge the vault already has.
- Scan `01 sources/claude/` directly for the concept notes you may need to enrich.

Done when you know which existing notes bear on what you are about to write.

## 4. Plan the notes

Route every fact you mined through two acceptance axes.

- **Generalizes** — it teaches something that holds on a *different* target, not a fact true only of this one.
- **Trigger-able** — a recognizable symptom, error, or task would send a future agent to retrieve it.

Two premises stand behind trigger-ability.
The wiki is retrieval-on-demand, so knowledge whose only value is firing *unprompted* does not belong there however well it generalizes.
And the reader is an amnesiac agent, so "the reader will internalize it" is never a reason to keep a note — trigger-ability, not memorability, is the axis.

A fact earns a **pull-channel note** only when it passes *both* axes.
A fact that fails either axis but is still useful to the target goes to the **push channel**, the target's `CLAUDE.md`: a **specific residue** that fails *generalizes* (the concrete repo-specific answer), or a **proactive rule** that generalizes but is not trigger-able (a verification-discipline or design-stance rule whose value is firing unprompted).
A fact that fails both axes and is useful to no one is dropped.

Most source lines split rather than route whole: the transferable **general lesson** goes to the pull channel, the **specific residue** it leaves behind goes to the push channel — recorded in the target's `CLAUDE.md` when that file does not already hold it.
So plan both destinations together, deciding for each pull-channel note whether it is new or an update to an existing note whose knowledge is now stale or thinner than what you have learned.

Keep each pull-channel note atomic — one transferable idea per note.
When a note carries two independent lessons, split it.
Write as many notes as the knowledge warrants; the count follows from atomicity, not from a target number.

Then build the contribution map: for every file you consumed, the notes it feeds and the exact sections that contributed — including any file that fed no note, recorded as feeding nothing.
The mapping is many-to-many — one file may feed several notes, and one note may draw on several files.

Done when every mined fact has a decided destination — pull note, push item, or explicit drop — every pull-channel note passes both axes and is atomic, and every consumed file, including those feeding no note, is mapped with its contributing sections named.

## 5. Present the plan and wait for approval

Write the plan as a self-contained HTML file to the session's scratchpad directory and give the user its path.
The report is a complete ledger of every mined fact's disposition, not only of what gets written, so the selection bar itself can be reviewed:

1. **Vault write-set (pull)** — each note to write or update, with its **trigger line**: one sentence naming the symptom, error, or task that would send a reader to retrieve it, and the `[[hub]]` wikilinks it belongs under.
2. **Contribution map** — for every consumed file, the notes it feeds and the exact contributing sections, including any file that fed nothing.
3. **Push write-set (target `CLAUDE.md`)** — each proactive rule and each specific residue to add, each existing entry to trim to its residue, and each pure-general entry to remove, with the exact text and where it lands.
4. **Ref-fixes** — each file holding a reference to a spec or task file about to be deleted, and how the reference is fixed or removed. These accompany the scaffolding deletion of step 7, not the target write-set.
5. **Flagged, not authored** — any `[[hub]]` a note links that does not yet exist under `02 tags/` or `03 index/`, and any push knowledge whose home is a hook or checklist rather than `CLAUDE.md` — surfaced for the user to act on by hand.
6. **Drops** — every mined fact considered and cut, one line of why each.

The vault write-set and the target-`CLAUDE.md` write-set are approved independently: the user may accept one and decline the other.
A declined target write-set degrades to flagged suggestions — reported for the user to apply by hand, written nowhere.
The ref-fixes and the scaffolding deletion are not a write-set to accept or decline — they follow from proceeding with the run and execute in step 7, gated only behind the vault writes.

Stop and wait for the user's explicit approval.
Write nothing and delete nothing until they approve.

Done when the user has ruled on each write-set.

## 6. Write the notes and reconcile the push channel

Write the approved vault write-set first.
Write each new note and update each changed one under the output area the branch declares, using the vault's note template (`99 meta/templates/note.md`): fill its `Tags:` line with the `[[hub]]` wikilinks the note belongs under, and its body with the distilled knowledge.
Link a hub whether or not its note exists yet — a dangling `[[hub]]` is a valid link and still feeds `/wiki` recall.

Then, if the target write-set was approved, reconcile the target's `CLAUDE.md`: add the proactive rules and any specific residue the file does not already hold, trim mixed entries to their specific residue, and remove the pure-general entries.
Removal is gated on capture — trim or remove an entry only when its general part is present in the wiki, written just now in this run or confirmed already there via `/wiki`, never on the intention to write a note.
If the target write-set was declined, write nothing to the target and leave its items as the flagged suggestions of step 5.

Done when the approved vault notes are written and, if approved, the target's `CLAUDE.md` is reconciled.

## 7. Clear the consumed scaffolding

With the notes written, perform the branch's cleanup — the branch file names exactly what to remove and what references to repair.
Deletion never precedes the writes of step 6.

Done when the branch's cleanup has run.

## 8. Report

Tell the user what you created, updated, and left untouched across both channels — vault notes written or updated, and the target's `CLAUDE.md` reconciliation applied or, if declined, left as flagged suggestions.
Repeat the suggested new hubs and any hook-or-checklist items from the report, so the vault's `02 tags/` and `03 index/` and the target's other channels can be filled in by hand.

Done when the summary names every note written or updated, every target edit applied or flagged, and every suggested hub.