ultralearn

name	ultralearn
description	Use when the operator wants to learn from real ultrapowers runs — harvest runs across projects, read them through five lenses, accumulate a redaction-guarded observation ledger, and distill human-gated improvement proposals. Two verbs - "ultralearn" (sense) and "ultralearn distill" (propose).

ultralearn — feedback loop from in-practice use

A developer tool that closes the loop from real ultrapowers runs back into the plugin. Deterministic Python harvests and merges; subagents read. All LLM work runs inside Claude Code — no API key, no external calls.

Verb 1 — ultralearn (sense)

1. Harvest. Run the harvester to detect real runs and build local bundles: python3 skills/ultralearn/scripts/harvest_runs.py Fleet runs (0.3.0 and later) come from their event log, not from ~/.claude/projects — the driver makes no Workflow tool call and runs in a sandbox, so the detector below cannot see them: python3 skills/ultralearn/scripts/harvest_fleet_runs.py --remote fleet-orchestrator.exe.xyz pulls each evidence tarball, or pass an unpacked run directory as a positional argument. It writes the same bundle.json + slice.md into the same cache, keyed by the fleet runId (run-30), so step 2 and step 3 are unchanged. --run run-30 restricts the pull; --force rebuilds a cached bundle. A fleet run directory is one holding an events.jsonl; runs 10–23 predate it and remain the Workflow-era harvester's (21–23) or the commissioned read's. The Workflow-era detector scans ~/.claude/projects, detects runs by an actual Workflow tool_result (not string mentions), and writes bundles to the gitignored cache ~/.claude/ultralearn/runs/<runId>/ (bundle.json + slice.md). Incremental: a watermark means re-runs only process new sessions. Sequential-engine drains (subagent-driven, inline) make no Workflow calls and are invisible to this detector by design — "0 new" there is correct, not a bug. Drains are sensed by commissioned transcript reads: after a drain, dispatch readers at the drain session's transcript with the same five lenses, including the redirect-round count, assigned to exactly one reader. Readers MUST set evidenceAbstracted: true (no bundle triggers the foreign rule), stamp engineVersion (plain version string — the repo release at drain time), and use the drain session id as runId; the merge guard then forces only origin: foreign — accepted. Promote trigger for a drain detector: a sense pass where commissioned reads miss or misread drain evidence; record the miss as a ledger finding. Runs 10–23 only — fleet evidence bundles read the commissioned way (#292). Superseded for any run carrying an events.jsonl (24+), which harvest_fleet_runs.py above harvests mechanically. For the older runs the drive layer is invisible to the detector too, so the evidence dir is first-class sense input, read the commissioned way. Layout (per run, under the repo's .claude/ultrapowers/fleet-runs-<date>/ or the orchestrator's <dbDir>-evidence/): gate-read-<runId>.json (the §W1d read, verbatim) + gate-read-<runId>.detail.json (triage detail), stat-<runId>.json (the raw control-plane payload), and sandbox-logs/<vm>-<stamp>/sandbox-logs.tgz holding shim.log, fleet-run.json, the engine transcripts (.claude/projects), and the in-repo run-*/ dirs. Dispatch one reader per fleet run with the bundle contents; readers set evidenceAbstracted: true, use the fleet runId as runId, and stamp engineVersion from the run's version stamp. Pilot corpus: .claude/ultrapowers/fleet-runs-2026-08-26/ (four distinct drive failure modes + one green engine run) and fleet-runs-2026-08-27/ (run-13, green).
2. Read. For each new bundle, dispatch a subagent with references/reading-lenses.md as its instructions plus the bundle's bundle.json and slice.md. The agent returns a JSON array of findings. Dispatch readers in parallel. Every reader applies all five lenses, including the open-ended frontier pass that catches emergent behavior.
3. Merge. Collect the findings and merge them behind the redaction guard. Build both bundle lookups once and pass them to merge_findings: origin_lookup, engine_lookup = bundle_lookups("~/.claude/ultralearn"), then merge_findings(findings, "docs/superpowers/observations/ledger.jsonl", origin_lookup, engine_lookup). origin_lookup(runId) reads origin from the cached bundle.json (fail closed to foreign); engine_lookup(runId) reads engineVersion.epoch, so each ledger entry records the ultrapowers version the finding was observed under — letting distill weigh whether a finding predates a fix. Then regenerate_digest(...) rewrites docs/superpowers/observations/ledger.md (the version shows as _(vX.Y.Z)_). Foreign verbatim evidence never lands — the guard drops it. Script: python3 skills/ultralearn/scripts/merge_ledger.py

Verb 2 — ultralearn distill (propose)

Read the accumulated ledger.jsonl, cluster recurring/co-occurring findings across runs, rank by frequency × severity × novelty, and draft improvement proposals — each mapped to a real surface (references/*.md, the routing hook, ultrawrite, report-format.md/SKILL.md, README). Draft each proposal against references/distilling-proposals.md, which is structural-first: make the defect inexpressible, not detected. A guard is a standing tax collected from every future run; a representation change is paid once — so before drafting any fix, name what made the defect possible and propose the change to that. A reactive per-defect guard is the fallback (on a recurring cluster the consolidation attempt is recorded first), machinery is earned by recurrence (first occurrence → prose or a watch-item; second → build — the parked list is the open watch-item-labeled GitHub issues, read at distill start via gh issue list --label watch-item --state open), and at most one additive guard per cycle is recommended for adoption. Weigh each finding's engineVersion: a cluster seen only under versions older than the current release may already be addressed — flag it as possibly-stale and confirm against the current engine before proposing a fix, rather than re-solving a closed problem. The same version stamp powers the reverse check: for each previously adopted proposal that carried a canaryMetric (required on any rigor-for-efficiency trade; default = the redirect-round rate every sensed run records), compare the canary across runs before and after the adopting version — a rising canary means the trade is failing, and drafting its reversal belongs in this distill's output. Output draft GitHub issues and/or spec stubs under docs/superpowers/specs/. Nothing is filed or committed without operator approval — present the drafts and let the operator choose. This human gate is the loop's governor, mirroring the pre-merge gate.

Deletion candidate (mandatory). Every distill cycle must nominate at least one simplification proposal — a rule, guard, knob, or subsystem the evidence suggests the engine could shed — even when ranked last. The sensing lenses hunt friction, so left alone the loop only ever accretes; the deletion candidate is its counterweight. Weak nominations are fine: name the candidate, what evidence would justify removing it, and what currently blocks removal.

Privacy (two tiers — the repo is public)

• Local, gitignored (~/.claude/ultralearn/): raw bundles, full slices, verbatim evidence, watermark.
• Committed (docs/superpowers/observations/): abstracted findings, metrics, local pointers only. Runs are classified home (this repo — verbatim OK) or foreign (any other project — evidence must be abstracted).