Extract valuable knowledge from Raw/ session dumps into Notes/ and Projects/.
\nRead ~/.cortex/config.json to get vault_path.\nIf the file doesn't exist, tell the user to run /cortexes:genesis first.
List the distill queue:
\ncortex-vec distill-queue --root <vault_path>/Raw\nThis is position-anchored: a Raw counts as distilled only if a\n<!-- distilled: ... --> marker appears in its header (before the first\n### User turn) or as its last non-empty line. Do NOT grep the\nmarker string — a pipeline meta-session's body quotes it dozens of times\n(it printfs markers onto other files), so grep -rL '<!-- distilled:'\nsilently drops genuine work from the queue. To check one file, use\ncortex-vec raw-state <file>.
Show the pending list count and ask to proceed.
\nSize the queue before opening any Raw:
\ncortex-vec distill-queue --root <vault_path>/Raw --stat\nPartition by RAW size (the raw column) and present the plan for\napproval (do not auto-run):
BUDGET_EXHAUSTED + distill-plan resume --new-session continuations.Carry remaining lanes forward with a cortex-takeoff baton. When a plan\nis mid-flight, record its plan_id in the baton — machine state lives in\nthe plan cache, the baton only points at it.
One Raw at a time. NEVER Read the full Raw file; NEVER judge from an\nL3/L3* projection. All original text arrives through bounded pages.
\nStart (or resume) the plan:
\ncortex-vec distill-plan start <raw-file>\nNote the returned plan_id. If it errors ANOTHER_PLAN_ACTIVE, ask\nthe user whether to resume that plan or distill-plan clear it —\nnever switch Raws silently.
Traverse the map:
\ncortex-vec raw-map <raw-file> --plan-id <id>\ncortex-vec raw-map <raw-file> --plan-id <id> --cursor <next_cursor>\nCards show kind / size / source range / preview / lexical anchors.\nThe map never says \"valuable\" or \"skip\" — choosing what to expand is\nthe main session's judgment.
\nExpand what needs reading. prose, output_body, ambiguous,\nopaque spans (and any card with preview_complete: false you need)\nmust be read via:
cortex-vec raw-span <raw-file> --plan-id <id> --span-id <N>\ncortex-vec raw-span <raw-file> --plan-id <id> --cursor <next_cursor>\nEarly positive stop: once you have concrete insight evidence, record\nit and stop expanding —
\ncortex-vec distill-plan evidence-add --plan-id <id> \\\n --char-start <s> --char-end <e> --label \"<short cite>\"\n(the range must already be reviewed). Full coverage is NOT required\nfor a positive candidate.
\nno-insight gate is mechanical: it requires\nno_insight_candidate_allowed: true from
cortex-vec distill-plan status --plan-id <id>\nwhich means the whole map was traversed AND every semantic /\nambiguous span was expanded. Do not propose no-insight before that.
On BUDGET_EXHAUSTED: stop reading, write the takeoff baton with the\nplan_id, and continue in a fresh session via
cortex-vec distill-plan resume --plan-id <id> --new-session\nThen apply has_insight() (below) to what you actually read.
has_insight() ruleAnswer Yes iff at least one passage anywhere in the Raw contains one of:
\nsrc/main.rs:226, checkDockerImage(), SynoBuildConf/unit-test).Insight commonly appears in any of these locations; treat them all as\nfirst-class:
\n★ Insight ───── callouts inside ### Claude blocks (Claude Code\nlearning-mode output).## Discoveries / ## Decisions sections (manually-edited\nRaws — still valid but not required).Answer No only when the entire Raw genuinely lacks concrete\nreferents — e.g., commands executed with no surrounding analysis, or\nvague statements like \"fixed it\" / \"works now\" / \"tested successfully\"\nwithout any mechanism / file / symbol / decision rationale anywhere in\nthe body.
\nThe has_insight() result above is a candidate verdict, not a\ndispatch decision. Always present the candidate to the user and wait\nfor confirmation, even when the verdict feels obvious. The user's\nanswer is binding regardless of the agent's tilt.
Use AskUserQuestion with:
No, note explicitly that no concrete\nreferent was found anywhere in the body.Yes (has insight) or No (no insight).(y)es — agree with candidate(n)o — override to opposite(s)kip-routine — Raw not worth dedup nor recording (use when the\nRaw is essentially a tool-recap / git-log dump that technically\npassed has_insight on a symbol but has no surrounding analysis)Yes → proceed to Step 3 (Stage 2).No → no-insight, go to Step 5 (mark) + Step 7 (log).skip-routine → skip-routine, go to Step 5 + 7 + 8.\nNo broadcast prompt (Step 9 is skipped for skip-routine).The plan ledger enforces the per-session raw-derived cap (default 100K\nchars, session_remaining_chars in every page). When a session has spent\na few plans' worth of budget, stop: commit finished Raws (Step 8) and\nhand the queue to the next session via cortex-takeoff. When Step 4\nquotes Raw text into a draft, verify the quote with grep -F against the\nsource, and keep the evidence ranges recorded via evidence-add.
When has_insight is Yes, optionally tag the extracted content for later lint:
\n| Tag | \nSignal | \nExample | \n
|---|---|---|
| 踩坑 (gotcha) | \nNon-obvious behavior, hidden trap | \n\"jsoncpp returns null for oversized doubles\" | \n
| 慣例 (convention) | \nProject-specific or internal practice | \n\"Service A reads config.json, Service B reads env vars\" | \n
| 決策 (decision) | \nWhy A over B, trade-off rationale | \n\"build-history.json over PID check because...\" | \n
These tags no longer gate extraction — they are reserved metadata for future lint capability. Safe to omit if the use case is unclear; downstream tooling treats absence as untagged.
\nOnly runs when Stage 1 returned Yes.
\nRead ~/.cortex/config.json:
jq -r '.distill.dedup_threshold_new // 0.45' ~/.cortex/config.json\njq -r '.distill.dedup_threshold_pending // 0.60' ~/.cortex/config.json\nDefaults: new = 0.45, pending = 0.60.
Pick the most content-ful insight passage anywhere in the Raw as the\nquery text — typically the densest ★ Insight ───── callout, the\nclearest analysis paragraph naming specific referents, or (for legacy\nRaws) the longest Discovery/Decision bullet. Aim for one self-contained\nchunk that mentions the concrete symbol / mechanism / decision; trim\nto roughly one paragraph. Run:
cortex-vec search \"<bullet text>\" --n 3\nIf the repo is known from Raw frontmatter, add --repo <name> when searching Projects-bound content.\n--repo narrows the Projects/ partition only; cross-repo Notes/ always appear in results regardless of the filter. Safe to add when the Raw is repo-specific.
Extract top-1 score from the JSON output.
If cortex-vec is unavailable (command errors, ECONNREFUSED, etc.): treat as score = 0.0, log dedup_top1: unavailable, prefer false-positive new over losing the insight.
Always ask the user, regardless of where score falls. The threshold\ntable below degrades from gate to candidate-outcome heuristic — it\nshapes the recommendation the agent surfaces, but never decides\nunilaterally.
\nUse AskUserQuestion with:
0.62).[[wikilink]] + ≤1-line excerpt from that page.(n)ew / (p)ending-merge / (s)kip-routine.| Score band | \nCandidate outcome to propose | \n
|---|---|
score < dedup_threshold_new | \nnew (low overlap with existing pages) | \n
dedup_threshold_new ≤ score < dedup_threshold_pending | \ndescribe both new and pending-merge neutrally; no strong tilt | \n
score ≥ dedup_threshold_pending | \npending-merge (strong overlap with top-1) | \n
When to tilt toward skip-routine (independent of score): the Raw\npassed Stage 1 only because of an isolated symbol mention with no\nsurrounding analysis — e.g., a git-log dump that happens to name a file\npath. Surface (s)kip-routine as a real candidate in such cases rather\nthan forcing new / pending-merge.
(n)ew → go to Step 4 (create) + Step 5 + 6 + 7 + 8.(p)ending-merge → skip Steps 4 and 6; go to Step 5 + 7 + 8 only.\nDo not write any new file or touch existing pages.(s)kip-routine → skip Steps 4 and 6; go to Step 5 + 7 + 8 only.\nMarker writes as (skip: routine).Projects/<repo>/ (repo from Raw file's repo: frontmatter)Notes/<category>/ (match existing categories)repos: to frontmatter if repo-specificThe marker must not be written until the plan is sealed (Notes/log\nall written, the user has confirmed the verdict):
\ncortex-vec distill-plan seal --plan-id <id> --expected-outcome <new|pending-merge|skip-routine|no-insight>\nAfter sealing, map/span pages are rejected (PLAN_SEALED); only then\nappend the marker.
Append exactly one marker to the Raw file, chosen by Step 3 outcome:
\n| Outcome | \nMarker | \n
|---|---|
new | \n<!-- distilled: YYYY-MM-DD → <target-relative-path> --> | \n
pending-merge | \n<!-- distilled: YYYY-MM-DD → pending-merge: <existing-path> (<score>) --> | \n
skip-routine | \n<!-- distilled: YYYY-MM-DD → (skip: routine) --> | \n
no-insight | \n<!-- distilled: YYYY-MM-DD → (no insight) --> | \n
Score formatting: two decimal places (e.g., 0.62, not 0.62345).\nDate: today, YYYY-MM-DD.
new outcome)Skip this step entirely for pending-merge, skip-routine, no-insight.
For each newly created file:
\nRun: cortex-vec upsert <relative-path>
Update _index.md: append the row under the matching ### sub-section — the\ntopic sub-section under ## Notes, or the repo sub-section under\n## Projects. Create the sub-section (with its table header) if it does not\nexist yet. Then bump the updated date in frontmatter.
Do NOT maintain an entries: count — the frontmatter has no such field, by\ndesign (see /cortexes:genesis).
For each Raw processed (regardless of outcome), append exactly one entry to <vault>/log.md:
## [YYYY-MM-DD HH:MM] distill | <raw-filename>\n- outcome: <new|pending-merge|skip-routine|no-insight>\n- target: <vault-relative path | omit for skip-routine and no-insight>\n- dedup_top1: <score → [[wikilink]] | \"unavailable\" | omit for no-insight>\n- repo: <value from Raw frontmatter repo: field | \"(none)\">\nThe agent should:
\n<vault>/log.md using either the Edit tool (preferred — adds the entry and preserves file integrity) or bash:printf '\\n%s\\n' \"$ENTRY\" >> \"<vault>/log.md\"\nWhere $ENTRY is the fully-substituted markdown entry.
Preserve exactly one blank line between entries (achieved by the leading \\n in the printf above, or by ensuring the Edit tool's new content starts with a blank line when appending).
Field rules:
\ntarget: present for new and pending-merge. Omit the line for skip-routine and no-insight.dedup_top1: include the score and top-1 page wikilink whenever Stage 2 ran (outcomes: new when score was computed, pending-merge, all interactive choices, skip-routine). Omit only for no-insight (Stage 2 did not run). For cortex-vec unavailable, write dedup_top1: unavailable.repo: use (none) if the Raw has no repo: frontmatter field.cd <vault>\ngit add Raw/ Notes/ Projects/ _index.md log.md\ngit commit -m \"distill: extract N entries from Raw\"\nIf auto_push is true in config: git push.
After the commit completes, close the plan (this verifies the only file\nchange was the expected marker):
\ncortex-vec distill-plan complete --plan-id <id>\nIf it returns RAW_CHANGED, the Raw has changed beyond just the marker —\nstop and report, do not retry.
For each Raw whose terminal outcome was new or pending-merge,\ndispatch to the cortex-broadcast skill inline immediately after\nStep 8's commit. Do not prompt the user — every broadcast-eligible Raw\nis broadcast.
Announce before dispatching:
\nDispatching broadcast for <raw-filename>...\nWhen broadcast completes, return here and move to the next unprocessed\nRaw.
\nFor outcomes skip-routine and no-insight, broadcast is skipped by\ndefinition (those Raws are ineligible).
The broadcast skill carries its own abort semantics — there is no gate\nat this layer:
\nquit to abort\nbefore any page commits. The Raw stays in the broadcast-eligible\nqueue (no | broadcast: marker is written), so it can be picked up\nby a future standalone /cortexes:broadcast run.abort\n/ cancel to end the session. Prior committed pages stand; the Raw\nmarker is left unchanged.To opt out entirely at the very first prompt broadcast surfaces, the\nuser just types quit at the Step 7 menu.
Raws historically marked | no-broadcast: <date> (from the previous\nprompt-based gate design) are still filtered out by cortex-broadcast\nStep 2's queue builder. This skill no longer produces that marker, but\nit remains a recognized legacy opt-out signal.