/epiphany

name: epiphany
description: Roam the Ultan memory library and surface ONE non-obvious, useful connection between distant entries — an on-demand "epiphany". Use when the user asks for a spark/insight/epiphany from their memory, wants a hidden cross-cutting pattern surfaced, asks "show me something interesting in my notes", or runs /epiphany. Can be scoped to a single project (e.g. /epiphany vol-predictor) to surface a cross-subsystem insight about that project. Read-only — it never writes to the library. Works by fanning out parallel scouts (Opus), converging over rounds with iterative grounding against the actual source artifacts the entries point at, then filtering to the single best connection.

Epiphany

A horizontal connection-finder for the Ultan library. The daemon already does *vertical* abstraction (rolling children up into a parent rule); this does the thing nothing else does — spots that two **distant, unrelated** entries share a latent structure, and surfaces the single best one.

The design rationale, and the one rule that makes this worth running: an epiphany is a *remote association* — a far pair with shared deep structure. Near-neighbours (same folder, same topic, already cross-linked) are obvious and worthless here. **The value lives in pairs that are far apart in the graph but structurally rhyme.** Everything below is built to find those and reject everything else.

Usage

/epiphany                  # free-roam the whole library (cross-domain)
/epiphany <seed/topic>     # free-roam, biased toward a region or theme
/epiphany <project>        # SCOPED: search one project, bridge across its subsystems

**Free-roam** finds the most surprising pair anywhere in the library. **Scoped** (e.g. `/epiphany vol-predictor`) constrains the search to one project and hunts a non-obvious connection *across its subsystems* (`model/entry-signal` ↔ `infrastructure/data-pipeline`, `evaluation` ↔ `policy`, …), optionally bridging up to a `global/` principle. "Distance" rescales from cross-domain to cross-subsystem — still genuinely far, and actionable for the project you're working in. Scoped is the better daily mode.

Method

The agent invoking this skill is the **orchestrator**. The scouts are the generators — and they do not fire once and stop. They **converge over rounds**, exchanging findings through a shared pool the orchestrator relays between them. (True peer-to-peer agent chatter isn't available; an orchestrator-mediated *blackboard* is the realistic — and more faithful — form: it mirrors a global workspace that competing processes read from and write to.) Run every step.

**0 — Map the territory.**

# free-roam: the whole library
python3 "<this-skill-dir>/inventory.py" --regions
# scoped to a project: partition it into subsystems (those become the scout regions)
python3 "<this-skill-dir>/inventory.py" --region projects/<PROJECT> --depth 3 --regions

**1 — Round 1: independent generation (blind).** Spawn **5–8 scouts in parallel — one message, multiple `Agent` calls — using Opus** (`model: "opus"`; connection- finding is reasoning-heavy, not just search). Keep them **blind to each other this round** — independent diversity is the asset you're protecting. Assign each a distinct **home region** (free-roam: a project or global subtree; scoped: one subsystem from step 0). Brief each:

> You are hunting for an *epiphany* — a non-obvious connection between two distant > entries in a personal knowledge library. Your home region is `<REGION>`. Run > `python3 <skill-dir>/inventory.py <SCOPE-FLAGS>` to see the territory. Skim your > home region, pick 2–4 entries that carry a real principle, read them fully. Then > deliberately bridge **OUT of your home region** — `<BRIDGE TARGET: another > subsystem of this project / another domain / up to a global principle>` — and find > entries whose *underlying structure* rhymes with yours (same failure mode, > trade-off, or mechanism) though the surface topic differs. Read those fully too. > Return **2–3 candidates**, each as: `a`,`b` (wikilinks) · `pattern` (shared > structure, one sentence) · `evidence` (a concrete quote/fact from EACH entry — no > paraphrase-only claims) · `nonobvious` (why it isn't already-linked/trivial) · > `sowhat` (the payoff). **Never pair two entries from the same region/subsystem** — > that's a cross-reference, not an epiphany. Fewer sharp candidates beat more vague ones.

**2 — Rounds 2..N: converge (the agents talk).** Pool every candidate and the entries scouts surfaced into a shared **blackboard**. Continue the SAME scouts with `SendMessage` (their context persists — they keep their own reasoning) and hand each the blackboard:

> Here is the full pool of candidates and entries the other scouts found. Do four > things: **(1) build** — find a stronger connection bridging ACROSS two *different* > scouts' material that none of them saw alone; **(2) challenge** — name the weakest > candidate in the pool and why it's coincidental, already-linked, or hollow; > **(3) ground** — for any candidate resting on a technical claim, do NOT trust the > entry's wording: follow its pointers (`sources:`, file paths, repo/tool names in the > body) to the **actual artifact** — locate it on disk (`find`/`grep`), read it, quote > the real thing — and refine or kill the bridge by what the source actually says; > **(4) vote** — your single best with one line of why. Do NOT just agree: if the pool > is converging on something shallow, or on a claim no one has checked against the > source, say so and pull it apart.

Assign **one scout a standing skeptic role** — its job is to refute, never to ratify, and in particular to **demand the source**: "which line of which file shows that?" This is the *lateral inhibition* that stops the group converging on a confident-but-wrong answer (see the notes below). Grounding is **iterative, not one-shot**: a technical claim gets checked against the artifact, the verbatim finding go