/cortex-distill

name: cortex-distill
description: >
  Distill raw session records into refined Notes and Projects. Use when
  the user says "提煉", "整理 raw", "distill", or "distill raw records".

Cortex Distill — Refine Raw Records

Extract valuable knowledge from Raw/ session dumps into Notes/ and Projects/.

Resolve Vault Path

Read `~/.cortex/config.json` to get `vault_path`. If the file doesn't exist, tell the user to run `/cortexes:genesis` first.

Step 1: Find Unprocessed Raw Files

List the distill queue:

cortex-vec distill-queue --root <vault_path>/Raw

This is **position-anchored**: a Raw counts as distilled only if a `<!-- distilled: ... -->` marker appears in its header (before the first `### User` turn) **or** as its last non-empty line. Do **NOT** `grep` the marker string — a pipeline meta-session's body quotes it dozens of times (it printfs markers onto other files), so `grep -rL '<!-- distilled:'` silently drops genuine work from the queue. To check one file, use `cortex-vec raw-state <file>`.

Show the pending list count and ask to proceed.

Step 1.5: Schedule the Batch (only when queue > 1 file)

Size the queue before opening any Raw:

cortex-vec distill-queue --root <vault_path>/Raw --stat

Partition by RAW size (the `raw` column) and **present the plan for approval** (do not auto-run):

• **Normal lane** — Raws whose raw size fits well inside one session

budget (default 100K chars of raw-derived output). Process a batch this session, strictly one Raw at a time.

• **Monster lane** — Raws whose complete review clearly exceeds one

session budget. One Raw per dedicated session; expect `BUDGET_EXHAUSTED` + `distill-plan resume --new-session` continuations.

Carry remaining lanes forward with a `cortex-takeoff` baton. When a plan is mid-flight, record its `plan_id` in the baton — machine state lives in the plan cache, the baton only points at it.

Step 2: Stage 1 — Has Insight (map-first)

One Raw at a time. NEVER Read the full Raw file; NEVER judge from an L3/L3* projection. All original text arrives through bounded pages.

1. Start (or resume) the plan:

   cortex-vec distill-plan start <raw-file>

Note the returned `plan_id`. If it errors `ANOTHER_PLAN_ACTIVE`, ask the user whether to resume that plan or `distill-plan clear` it — never switch Raws silently.

2. Traverse the map:

   cortex-vec raw-map <raw-file> --plan-id <id>
   cortex-vec raw-map <raw-file> --plan-id <id> --cursor <next_cursor>

Cards show kind / size / source range / preview / lexical anchors. The map never says "valuable" or "skip" — choosing what to expand is the main session's judgment.

3. Expand what needs reading. `prose`, `output_body`, `ambiguous`, `opaque` spans (and any card with `preview_complete: false` you need) must be read via:

   cortex-vec raw-span <raw-file> --plan-id <id> --span-id <N>
   cortex-vec raw-span <raw-file> --plan-id <id> --cursor <next_cursor>

4. Early positive stop: once you have concrete insight evidence, record it and stop expanding —

   cortex-vec distill-plan evidence-add --plan-id <id> \
     --char-start <s> --char-end <e> --label "<short cite>"

(the range must already be reviewed). Full coverage is NOT required for a positive candidate.

5. `no-insight` gate is mechanical: it requires `no_insight_candidate_allowed: true` from

   cortex-vec distill-plan status --plan-id <id>

which means the whole map was traversed AND every semantic / ambiguous span was expanded. Do not propose `no-insight` before that.

6. On `BUDGET_EXHAUSTED`: stop reading, write the takeoff baton with the `plan_id`, and continue in a fresh session via

   cortex-vec distill-plan resume --plan-id <id> --new-session

Then apply `has_insight()` (below) to what you actually read.

`has_insight()` rule

Answer **Yes** iff at least one passage anywhere in the Raw contains one of:

• A specific symbol / file path / line number (e.g. `src/main.rs:226`, `checkDockerImage()`, `SynoBuildConf/unit-test`).
• A specific bug mechanism or root-cause statement (e.g. "filter must fully match repository, substring not supported").
• A specific decision rationale in the form "X over Y because Z" — not bare "use X".

Insight commonly appears in any of these locations; treat them all as first-class:

• `★ Insight ─────` callouts inside `### Claude` blocks (Claude Code

learning-mode output).

• Tables comparing options, summarizing a bug, or laying out an attack

chain.

• Prose paragraphs that walk through analysis, root cause, or

trade-off rationale.

• Legacy `## Discoveries` / `## Decisions` sections (manually-edited

Raws — still valid but not required).

Answer **No** only when the entire Raw genuinely lacks concrete referents — e.g., commands executed with no surrounding analysis, or vague statements like "fixed it" / "works now" / "tested successfully" without any mechanism / file / symbol / decision rationale anywhere in the body.

Present judgment to user (mandatory)

The `has_insight()` result above is a **candidate verdict**, not a dispatch decision. **Always present the candidate to the user and wait for confirmation**, even when the verdict feels obvious. The user's answer is binding regardless of the agent's tilt.

Use `AskUserQuestion` with:

• **Evidence**: 1–3 concrete excerpts from the Raw supporting the

candidate (file:line, ★ Insight callout, decision rationale, table, etc.). When the candidate is `No`, note explicitly that no concrete referent was found anywhere in the body.

• **Candidate verdict**: `Yes (has insight)` or `No (no insight)`.
• **Options**:
• `(y)es — agree with candidate`
• `(n)o — override to opposite`
• `(s)kip-routine — Raw not worth dedup nor recording` (use when the

Raw is essentially a tool-recap / git-log dump that technically passed `has_insight` o