mulch-record-from-evidence

mulch-record-from-evidence

Use this skill when you have just finished a chunk of work in the mulch repo and need to preserve the durable insights as mulch expertise. It converts concrete evidence — what you changed, why, and what broke along the way — into precise ml record calls, instead of inventing ritual filler records. Unrecorded learnings are lost; vague records are noise. The goal is a small number of high-signal records, each backed by real evidence.

When NOT to record

Skip recording entirely if the session produced no durable insight: a trivial typo fix, a dependency bump with no behavioral change, or a revert. A record that just restates the diff is noise. Only record a convention, pattern, decision, or failure that a future agent would benefit from knowing before touching the same area.

Pre-flight

Confirm you are at the mulch repo root and the store is healthy:

ml status                         # per-domain health + record counts
ml doctor                         # exits 0 when records are intact

If ml doctor reports problems, fix the store first (see RUNBOOK.md §4) — do not record on top of a corrupt JSONL.

Procedure

1. Gather the evidence

Let mulch tell you what changed and which domains are implicated:

ml learn                          # changed files + suggested domains
git status                        # uncommitted work
git diff --stat HEAD~1            # what the last commit touched
git log --oneline -5              # recent commit subjects

If the work maps to a tracker, pull its context too:

sd show <issue-id>                # the seeds issue you were working

Write down, for each insight candidate: what you learned, which file or subsystem it concerns, and what evidence supports it (a commit sha, a changed file, a failing test you fixed).

2. Classify each candidate

For every insight worth keeping, decide:

• Domain — which .mulch/expertise/<domain>.jsonl it belongs to. Run ml status to see existing domains; match the subsystem you touched (e.g. CLI behavior → cli, test infra → testing, type conventions → typescript). Respect the project's per-domain allowed_types rules printed at the top of ml prime — a domain may only accept certain types.
• Type — convention (a rule to follow), pattern (a reusable approach that worked), decision (a choice made and its rationale), failure (something that broke and how it was resolved), reference (an external fact/link), or guide (a procedure). Custom project types (e.g. flake_symptom, release_decision) carry extra required fields — ml record will tell you which.
• Classification — foundational (permanent truth), tactical (relevant ~14 days), observational (relevant ~30 days). Default to the shortest shelf life that fits; only mark foundational when the insight is a lasting invariant.