| 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)
- 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.
- 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.
- 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.
- 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.
- 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
- 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.
- 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).
- 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.
- 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).
