# Mint Atoms > 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 - Skill: `manutej/mint-atoms` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add manutej/mint-atoms` - Raw SKILL.md: https://api.skillmd.com/api/skills/manutej/mint-atoms/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: manutej (https://skillmd.com/u/manutej) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/manutej/mint-atoms --- # 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- · · `, 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//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- · ` 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:` 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).