Eureka/SKILL.md
Meta Vens eea514aa31 Publish Eureka, the Claude Code faculty pipeline skill
Eureka is extracted from the Aetheria CultCache migration and is the Claude
Code counterpart of Epiphany. It covers the faculty loop, brief templates,
the cut map shape, the postmortem template, the worked example, a dated
comparison with Epiphany, and a changelog tying each rule to its evidence.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 20:15:10 +02:00

15 KiB

name description
eureka Eureka runs a foundation change as a faculty pipeline for Claude Code agents. It is the skill counterpart of Epiphany. The root agent acts as Self and routes the work. The target shape is written first, Imagination maps the cut, Hands executes one cut at a time, Soul verifies by trying to falsify what Hands promised, a Mind Steward keeps memory honest at phase boundaries, and the operator rules on real forks. Use it for any migration, rebuild, teardown, cross-repo or cross-runtime change, infrastructure swap, or multi-cut refactor, especially on shared GameCult substrate (CultLib, CultCache, CultNet, CultMesh, CultMath). Also use it when the operator says "Eureka", "map the cut", "Imagination pass", "Soul pass", "Hands", "mini Epiphany loop", or "make this migration look like the last one", or asks to plan and land a change too big for one diff, even without naming the pipeline.

Eureka

Eureka is the pipeline used by Claude Code agents. It sits next to Epiphany, the running organism in F:\Projects\Epiphany, and shares its faculty vocabulary. The difference is substrate:

  • Epiphany keeps its findings in typed, admitted state that can be queried by exact filter. Semantic search over that state is planned through voidbot; Epiphany removed her own vector stack in 856648de.
  • Eureka currently keeps them in committed docs (the target and the cut map), subagent reports and memory files.

Giving Eureka agents typed state tools is the intended next step; see references/changelog.md.

This pipeline lands changes that are too large or too foundational to trust to one agent's judgment. It turns "migrate X" into a sequence of small, verified ownership changes. Each cut is specified tightly enough that Hands barely has to read, and each one is falsified by an agent that did not write it.

It exists because the failure it prevents is common and quiet: one agent plans, implements, tests and reports on its own work. The tests then pin the agent's spelling, not the operator's invariants, and the report is written by the party with the most reason to believe it. In the Aetheria CultCache migration (2026-09-12..15), 29 of 32 Soul passes found real defects that Hands' own green tests had passed, about 75 in all: deadlocks, lost writes, a wire-parity split between runtimes, untested operator rulings, and a writable catalog in the editor. See references/postmortem-cultcache.md for the evidence.

The faculties

Faculties are postures, not personalities. The root agent is Self. It routes work, keeps the maps, commits the maps, and talks to the operator. Delegate every other faculty to a subagent with its own brief. A faculty that grades its own work has lost the point.

Faculty Runs against Produces Must not
Imagination the Body (source, docs, probes), plus the target the cut map: the target shape specified to file:line commit code, choose a product fork silently
Hands one cut of the map small pushed commits, a report with evidence redesign the spec, work around a fork, update the map
Soul Hands' executed commits findings, CONFIRMED or PLAUSIBLE, each with file:line and a failure scenario edit, commit, or review a plan (a pass on a plan is Imagination)
Mind Steward memory surfaces named mutations and proposals touch Body code, restate what an owner doc already records
Eyes (optional) history, transcripts, logs a facts file with evidence pointers conclude or recommend
Operator forks and product meaning rulings (not an agent)

The operator's doctrine defines the faculties. Read the Soul and Imagination lines of the operational litany in ~/.claude/CLAUDE.md. In short, a pass is named by what it produces, so a pass over a plan is Imagination, and a plan is finished when Hands can go straight to the cut.

The loop

0. Map the substrate, scope, target

  • Map the real substrate before you propose anything. Run parallel read-only exploration of the old system and the new one, of any prior attempts and why they failed (git history, rollbacks), and of every consumer across repos.
  • Write the target document: the ends, not the means. Name the invariants that must survive (wire parity, one owner per decision, what the operator refuses to lose), the canonical implementations, and what is explicitly not a consumer. For example, AetheriaEve was "taxidermy", and saying so up front saved every later pass from considering it.
  • State the scope boundary out loud. The earlier Aetheria attempt failed because it bundled cache, mesh, eve and daemons into one change. One foundation per pipeline.
  • Dispatch the Mind Steward before the first consequential action.

1. Imagination maps the cut

Brief an Imagination agent to produce the cut map: an ordered list of cuts against the current Body. Each cut carries:

  • repo and branch;
  • deletes first, with exact paths and line counts;
  • keeps and moves;
  • adds;
  • per-file changes with file:line against a named HEAD;
  • an authority map for anything that changes ownership: owner, inputs, outputs, derived state, forbidden writers, shared paths, deletion line;
  • verification: exact builds, tests with the rule each one pins, negative greps, and what only the operator can check;
  • a subtraction-ledger estimate.

Subtraction comes from a consumer audit of the public surface, not from taste:

  • Count real use across every project the operator works in before sizing or cutting a feature, not only one runtime's repos. Atomic commit was nearly cut as "unused in C#", even though Ghostlight and Epiphany needed it. Call counts decided whether compare-exchange was in scope.
  • A surface with design intent but no consumer is parked at a tag with a note, not deleted. SoA was parked at parked/cultcache-soa.
  • A capability the operator has needed across projects is reshaped, not removed, even when its current consumers are only tests.
  • Where the operator's own original code exists, it is the style bar.

Keep subtraction cuts separate from behaviour cuts, so Soul can falsify each on its own.

Before specifying a domain concept, ask the operator what it is for. In the CultCache migration Imagination inferred loadouts' purpose from a broken legacy menu. The operator then redefined them three times in one evening, and each redefinition reworked shipped code. Stores, UI and pricing all follow from purpose, so the question is cheaper than the rework.

Design order as data, not as scheduling. A ticket system that serialized delivery was built, deadlocked, and was deleted for a per-cache sequence number. When a map needs ordering or concurrency guarantees, prefer carrying the order in the data the consumer reads.

Imagination must establish mechanism claims by running code: probes, scratch builds, decoding a real file. It must not reason from names. A map built on unprobed claims is where bad cuts come from. Real forks come back as explicit operator questions with a recommended option, never chosen silently.

Iterate the map with further Imagination passes, not Soul passes, until Hands could go straight to the cut. Commit the map; it is the durable record of the means.

Templates are in references/briefs.md and references/cut-map.md.

2. Operator rulings

Bundle the open questions. Give each one options and a recommendation, and say what depends on the answer. Record every ruling in the map, dated, with the operator's words when they carry meaning the paraphrase would lose. When a ruling supersedes an earlier one, mark the old text as history instead of leaving two live designs.

Distinguish a real fork from a default. "Should I use the conventional thing" is not a question. "3-5 are not decisions," as the operator put it, is the failure of asking about non-decisions.

3. Hands executes one cut

Brief Hands with the cut's section of the map, the standing rulings restated briefly, and the verification. The brief says:

  • Follow the spec, do not redesign. If the Body contradicts the spec, fix the smallest thing that keeps the spec's intent true and report the discrepancy. If it is a real fork, stop and report.
  • Gaps are filled in their owner, never worked around locally. If CultMath lacks a function, CultMath gets it; the consumer does not grow a helper.
  • Delete before adding. No shims, no compatibility layers the map did not name.
  • Small commits, each pushed, with explicit paths. See the git rules below.
  • Every operator ruling and every new rule gets a test that fails under its own mutation. Hands runs the mutations against the final spelling of the code and restores afterwards.
  • Report: commits (and which don't build), verification output, mutation results, spec discrepancies, forks, structural delta. Hands never updates the map.

Parallel Hands are fine when they touch different repos or worktrees. They are not fine in the same working tree, and never while a Soul pass reads that tree.

4. Soul falsifies

Brief Soul on the exact commit range, with the operator invariants and Hands' promises listed as claims to falsify. Point it at the specific places a shortcut would hide. Soul:

  • reruns builds, tests and captures itself instead of trusting the report;
  • reruns a selection of Hands' mutations, and designs its own that are not plain reverts;
  • builds scratch probes to reach behaviour the tests cannot see: round-trip every document type, decode a legacy file independently, compile the shader with the real compiler, run the other runtime's decoder;
  • checks the invariant at the layer where it would actually fail (wire bytes, another runtime, the editor, the GPU), not only in the unit test;
  • reports each finding as CONFIRMED or PLAUSIBLE, with file:line, a failure scenario and severity, then lists the promises that held.

Soul works read-only. It creates temporary worktrees for anything that needs a different checkout, removes them afterwards, and leaves every tree clean.

5. Triage and repeat

For each Soul finding, decide:

  • fix now: brief Hands with the finding and the target shape;
  • operator fork: ask, with a recommendation;
  • record as a follow-up: the map gets the item, the file and the reason it can wait.

Run Soul again on the fix batch. Do not cap the Soul loop early on a foundation cut. In the CultCache migration, Cuts 6 and 6b each needed four Soul passes, and the later passes still found real defects. Stop when a pass finds nothing that blocks, or only findings the operator chooses to record.

When the same kind of finding recurs, the brief was missing context. Fix the brief template, not only the instance. That is how "operator rulings each need their own failing mutation" entered the Hands brief.

A release or tag is a cut and gets its Soul pass before the tag is pushed. The CultCache release cut skipped Soul. Its stale DLLs, SHA-bound byte checks and silently skipped publish jobs surfaced only after tags were out. CultLib 1.0.58 shipped a wire-parity defect that was found and corrected 74 minutes later.

6. Land, record, steward

After each cut:

  • Self updates the map's status header: what landed at which SHAs, what was verified, what Soul found, what was recorded.
  • Self reconciles the subtraction ledger against what actually landed. A miss is allowed, but it must be explained. The CultCache core missed its size target by roughly 1,200 lines, and nobody looked, because the ledger stopped being updated after Cut 4.
  • Self commits and pushes the map. Hands and Soul never touch it.
  • At phase boundaries, a Mind Steward pass moves durable rulings to their owners, retires superseded memory, and falsifies at least one persisted claim.

At the end, Self writes the postmortem (see references/postmortem-template.md) and reconciles the target doc with the Body.

Self's discipline

  • Keep the maps committed and current. Hands will read stale text as live design. After a ruling changes a design, sweep the map and the target doc for the old version the same day.
  • One owner per decision, in code too. When Hands moves a decision partway, for example the charge moving into Materialize while affordability stayed in the menu, send it back. Split authority is the defect Soul most often finds.
  • Relay findings plainly. The operator reads Self's summaries, not the agent reports. Say what broke, how it would fail, and what is being done.
  • Choose models by how critical the pass is. Put the scarce strong model on Imagination and on Soul passes over cuts that put the foundation at risk. Hands, search, probes and stewards take the default model. A cheaper Soul model does not soften its brief: it still attacks, invariants first. When Fable ran out mid-migration, Opus carried every faculty and Soul still found the defects.
  • A subtraction budget is pressure, not a metric. Say so when you set it, so Hands knows escalating a miss with an argument is allowed. Treat a suspiciously clean hit as a sign that unrelated code was deleted to meet the number.
  • Track Soul's hit rate, not the ceremony. If an attacking pass stops finding anything across cuts, ask whether it has started confirming instead of attacking. Also ask whether it inspected an adjacent artifact rather than the thing that actually runs.
  • Never claim an agent's result before its notification arrives.

Git and tooling rules (scars)

  • Stage explicit paths. Never git add -A. It swept an untracked local settings file into history.
  • Write commit messages with the Write tool to a uniquely named scratch file, then git commit -F. PowerShell 5 here-strings break -m quoting, and its Out-File/Set-Content write a BOM into message files. Shared filenames like msg1.txt collided between parallel agents.
  • Push at most three tags per push. GitHub skips tag-triggered workflows when one push carries more tags, so the npm and PyPI publish jobs silently never ran.
  • Keep release byte checks commit-independent. Exclude the source revision and Source Link from the version, build non-incrementally, and use /Brepro for native code. A committed DLL otherwise always carries its parent's SHA.
  • Run long builds detached, with a log and a PID, and poll. Unity batchmode and similar builds must never be one attached call. Revert incidental asset churn afterwards, such as Unity's SDF font asset.
  • Before a mass-spawn or process-launching probe, read how the child chooses its role. A probe that relaunched its own executable fork-bombed the workstation three times.
  • Pin sibling checkouts with a guard that checks revision and cleanliness. Scope the guard to projects that actually reference the sibling.

Adapting the pipeline

Small cuts can merge Imagination into Self when the map is already current, but never merge Soul into Hands. Non-code migrations (content, data, docs) keep the same loop: the "tests" become captures and independent decodes. The shape to preserve is separate planner, executor and falsifier, with the operator ruling forks and memory kept honest.

Record changes to this skill in references/changelog.md, with the evidence that motivated each one.