mint-atoms

name	mint-atoms
description	The compounding engine of signal-forge — captures reusable knowledge atoms from every run and every human correction, traces each correction to the exact factory line that allowed it, writes append-only ledgers with a same-transaction discoverability index, and refreshes decay-prone atoms on a cadence so run

Mint-atoms — capture → retrieval → refresh, or the factory decays

This skill IS the Capture step of every other skill's Frame→Do→Review→Capture loop, and it owns the two steps that make capture pay off: retrieval (atoms consulted at the start of every run) and refresh (rot maintenance on a cadence). It implements the Improve : Fact → Fact endofunctor of ../forge/references/meta-meta-map.md: feedback and finished runs are corrections; applying them and bumping versions iterates the factory toward a fixed point. Capture that never gets retrieved is a journal, not a flywheel — this skill refuses to be a journal.

This skill runs its own loop on itself: Frame (type the trigger + inputs) → Do (mint/trace/edit) → Review (checkable predicates below) → Capture (append ledger AND update INDEX in one transaction). It is not "done" on vibes; done means predicates checked and the index reflects the write.

H1 — Typed input slots and outputs

Fill at invocation; UNKNOWN is legal, never invented.

TRIGGER:        {feedback | run-DONE | batch-rollup | refresh-cadence}
RUN_SLUG:       str|list[str]|n/a   # yyyy-mm-slug; list for batch-rollup; n/a for a pure refresh sweep
FEEDBACK:       str|n/a             # verbatim human correction — required when TRIGGER=feedback, else n/a
VERTICAL:       str|UNKNOWN         # the run's vertical/use-case, drives which atoms to refresh & tag
ARTIFACT_TOUCHED: str|n/a           # which deliverable the feedback lands on

OUTPUTS (by trigger):
  feedback       → feedback-loop.md entry (traced) · proposed factory diff (forge executes it) · ≥0 atoms · INDEX updated
  run-DONE       → ≥1 atom in atoms.md · INDEX updated · retrieval-effect note (which loaded atoms fired)
  batch-rollup   → portfolio-analytic atoms (win/loss patterns across N runs) · dedupe/merge report · INDEX updated
  refresh-cadence→ per due atom: kept|updated|replaced|archived with dated note · INDEX due-dates advanced

Ledgers live in the workspace (create with headers if missing): FACTORY/atoms.md, FACTORY/feedback-loop.md, FACTORY/INDEX.md. Formats: references/ledger-protocol.md.

H2 — Artifacts and acceptance

• Atom — formal format in references/atom-schema.md: greppable header ATOM-<seq> · <type> · <one-line claim>, typed fields, controlled tag vocabulary, decay date where decay-prone, provenance (run slug + feedback ref), scope + anti-scope, merge/conflict rules.
• Ledgers + INDEX — formats and the transactional rule in references/ledger-protocol.md.
• Refresh pass — decay classes, per-atom procedure, cadence trigger, portfolio analytics in references/refresh-policy.md.

Acceptance (all triggers): every atom greppable by header · typed · tagged from the controlled vocabulary · decay-dated if its type is decay-prone · provenance present (source + date, never mint without both) · INDEX updated in the SAME transaction as the ledger write (no orphan atoms). Per-trigger checklists live in the reference files.

H3 — This skill is Capture (make its own loop explicit)

Other skills call mint-atoms as their Capture step. Mint-atoms still runs Frame→Do→Review→Capture on itself: Frame the trigger; Do the mint/trace/refresh; Review against the checkable predicates (H6); Capture by appending the ledger and updating INDEX atomically. The recursion terminates — mint-atoms captures atoms, not atoms-about-capturing — but the discipline is identical at every level.

The three trigger paths (procedures with blocking predicates)

Path A — TRIGGER=feedback (the feedback→line tracing protocol; this skill defines H10 for everyone)

1. Log verbatim. Append to feedback-loop.md: date · RUN_SLUG · ARTIFACT_TOUCHED · the correction quoted exactly. BLOCK: refuse untraceable "just be better" feedback — you cannot trace a vibe to a line. Log it anyway as a trace-gap finding ("no line found: procedure gap?"), which is itself an atom candidate, and stop the edit path.
2. Trace to the line. Name the specific factory slot, derived-slot rule, or procedure line that ALLOWED the miss. "Deck struck the wrong tone" → CHANGE_APPETITE mislabeled or unread, not "write better decks." Record the traced line in the ledger entry. BLOCK: no factory edit proceeds until a candidate line is named or the trace-gap is logged.
3. Propose the diff. Write the minimal line-level change (a slot comment, a rule, a procedure step). Hand it to the forge skill's edit path — forge owns the factory edit; mint-atoms never silently edits a factory (H8). The version bump + changelog entry naming this feedback as source is forge's job; verify it happened.
4. Generalization check. Re-test the proposed edit against 2–3 other instances of the category. A fix that only helps the last deal is overfit — generalize it or mark it instance-bound. Record the result.
5. Mint + propagate. Mint any atom the correction earned (often a phrase, objection-pattern, or tell-pattern). If the correction invalidates shipped artifacts, route regeneration through run-factory — never hand-patch (functor law, meta-meta-map.md).

Path B — TRIGGER=run-DONE

1. Retrieval-effect note first. Read prospects/<slug>/00-intake-digest.md's "atoms consulted" list (see H4). Note which loaded atoms actually fired (shaped an artifact) vs. sat unused — unused-but-loaded atoms are refresh candidates; atoms that should have existed but didn't are mint candidates.
2. Mint ≥1 atom. Per atom-schema.md types: benchmark, gate, template, phrase, tell-pattern, triage-route, objection-pattern, pricing-signal, sequence-conversion, factory-pattern. Each self-contained with source + date, scope, anti-scope. BLOCK: a run cannot be DONE with zero atoms minted (factory DONE predicate, factory-schema.md §7).
3. Dedupe on write. Before appending, grep INDEX for the same claim — apply the merge rules (atom-schema.md): same claim → merge with union scope + newest evidence; contradicting claim → keep both, flag CONFLICT for human triage.
4. Capture atomically. Append atoms.md AND update INDEX (new atom under its tag/type/vertical buckets, decay due-date registered) in one transaction.

Path C — TRIGGER=refresh-cadence (and batch-rollup)

Execute references/refresh-policy.md: for each due atom, re-verify against sources → keep / update / replace / archive with a dated note; advance INDEX due-dates. Cadence trigger: before any run in a vertical, refresh that vertical's overdue atoms; monthly, a portfolio-wide sweep. For batch-rollup, additionally extract win/loss patterns across the named runs (which wedges converted, which pricing shapes won, which objections recurred) and mint each conclusion as its own atom with the runs as evidence — analytics are atoms too.

H4 — Scale-native: retrieval-at-intake contract (capture without retrieval doesn't compound)

This is the load-bearing half. Other skills MUST query atoms at run start; mint-atoms defines how:

• At intake, run-factory (Stage 0) and hunt grep FACTORY/INDEX.md by the run's VERTICAL + use-case/stage tags, pull the matching atoms, and list them in 00-intake-digest.md under "atoms consulted" — so their effect on the run is traceable at DONE (Path B step 1). An atom that shaped an artifact but was never listed is an untraceable influence; an atom that should have been loaded but wasn't is a retrieval defect, logged.
• Portfolio rollups across N runs feed Path C: cross-run analytics become atoms with runs as evidence.
• Dedupe/merge rules (atom-schema.md) keep the ledger from bloating as N grows: identical claims merge, conflicts stay flagged for humans. The INDEX is the retrieval surface that makes N atoms findable in O(grep), not O(read-everything).

Wired in v0.2.0: run-factory Stage 0 (SKILL stage table + orchestration-protocol.md Stage-0 predicate) and hunt (H3 Frame) now grep FACTORY/INDEX.md at intake and write the ## atoms consulted block — the block is a blocking predicate (empty only when INDEX has no match). The retrieval half of the compounding loop is live.

H5 — Judgment in references

What counts as a mintable atom vs. noise, how hard to filter, when a fix is overfit, decay-class boundaries, and merge-vs-conflict calls all live in the three references — not inlined here.

H6 — Checkable predicates

• Every atom is greppable by its ATOM-<seq> · <type> header. grep -c '^ATOM-' atoms.md equals the INDEX atom count.
• Every atom carries ≥1 controlled tag and a provenance line (source + date).
• Every decay-prone atom carries a recheck:<date> field; the same date appears in INDEX due-dates.
• No ledger write exists without its INDEX entry (no orphan atoms; the transactional rule).
• Every feedback-loop.md entry names a traced line or an explicit trace-gap finding.

H8 — Core invariants

Atoms are example-agnostic where possible; instance-bound atoms say so in their scope field. Silent factory edits are prohibited — forge owns edits, every bump carries a changelog naming its feedback source. No atom is minted without a source and a date. Regenerate on invalidation; never hand-patch (meta-meta-map.md).

H9 — DONE predicate and refusal conditions

DONE when: the trigger's outputs (H1) exist · every new/changed atom passes H6 · INDEX reflects every write in the same transaction · for feedback, a traced line or logged trace-gap exists and any factory edit was executed by forge with a changelog · for run-DONE, ≥1 atom minted and the retrieval-effect note written · for refresh, every due atom has a dated keep/update/replace/archive verdict.

Refuse to: trace or edit on untraceable "be better" feedback (log the trace-gap finding instead) · mint an atom without a source + date · edit a factory directly (route through forge) · write a ledger entry without updating INDEX · let a run close with zero atoms minted or zero atoms consulted.

H10 — The feedback→line-level tracing protocol (owned here for the whole plugin)

Correction → candidate factory line(s) → proposed diff → forge executes the bump. Every skill that receives feedback routes it here; mint-atoms guarantees each correction lands on a line, not a vibe, and that untraceable feedback is itself captured as a procedure-gap finding. See Path A.

References

• references/atom-schema.md — the formal atom format, type set, tag vocabulary, merge/conflict rules.
• references/ledger-protocol.md — atoms.md / feedback-loop.md / INDEX.md formats, the transactional rule, and the retrieval contract for other skills.
• references/refresh-policy.md — decay classes, refresh procedure, cadence trigger, portfolio win/loss analytics.
• Shared law: ../forge/references/factory-schema.md (§7 DONE, §8 self-improvement loop) · ../forge/references/meta-meta-map.md (the Improve endofunctor).