writing-motoko: general Motoko items dropped vs prior coverage (persistence flags, M0220/M0141/M0064/M0145, Text.join/variant-paren pitfalls, reserved-keyword list, equality breakdown)

[marc0olo]

Thanks again for the quick fixes on the earlier issues!

Context: we're migrating our Internet Computer skills site (dfinity/icskills) to sync writing-motoko, migrating-motoko-actors, and troubleshooting-motoko-migrations from here. As part of that we compared the content we're replacing (our older Motoko skill) against the new writing-motoko corpus (SKILL.md + api-reference.md + examples.md + references/*).

writing-motoko is richer than our old skill in most areas (mops toolchain, Nat-arithmetic safety, numeric-conversion hygiene, text search/case folding, array sorting, a much larger error table, the API reference). But a handful of general (non-Caffeine) Motoko items our old skill covered aren't in the new corpus anywhere. We'd like to sync the core generically, so rather than carry these as local patches we'd prefer they live upstream — could you consider adding them? (If you'd rather they stay out of scope, that's fine too — we'll drop them on our side. Just want an explicit decision so we're not silently diverging.)

1. How enhanced orthogonal persistence is actually enabled

The body says state persists "without the stable keyword" but never explains how EOP is turned on. On Caffeine the mops toolchain sets this automatically, so it's invisible — but a general reader compiling with moc/mops manually hits M0220 with no guidance. Our old skill had:

--default-persistent-actors          all actors are `persistent`, no `stable` keyword needed

--enhanced-orthogonal-persistence is on by default. Without --default-persistent-actors, plain actor { } errors with M0220 — write persistent actor { } instead (the persistent keyword is transitional; actors become persistent-by-default in a future major moc release).

Plus the auto-fixable style-enforcement warnings that back the skill's own conventions: -W M0236 (non-dot-notation calls), -W M0237 (redundant explicit implicit args), -W M0223 (redundant type instantiation).

2. Error-table rows dropped

Present in our old table, not in the new one:

Error	Meaning	Fix
M0220	actor should be declared persistent	--default-persistent-actors or persistent actor
M0141	type/let declared before the actor body	move them into the body / into types.mo
M0218	redundant stable keyword	remove stable (plain var is auto-stable)
M0064	misplaced '!'	wrap in do ? { ... }
M0145	pattern does not cover value	add missing cases or case _

(We had previously flagged M0064 and M0145 upstream at caffeinelabs/motoko — issues #6157 and #6156 — but since that repo is being retired, re-surfacing here.)

3. Pitfalls dropped

• Text.join parameter order — iterator first, separator second: Text.join(["a","b"].values(), ", "). Easy to invert.
• type/let before the actor body (M0141) — only imports may precede the actor; move types into types.mo.
• Parenthesize variant tag arguments — #tag(x), never #tag x (#tag 1 + 2 parses as #tag(1) + 2).
• Never annotate lambda argument types — the compiler infers them; annotating is redundant and often wrong.

4. Reference material dropped

• Full Reserved Keywords list. The new corpus names query/label as reserved (Critical Requirements + one error row) but has no enumerated list. Our old skill listed all of them (actor and assert async await break case … with, plus the async*/await*/await? note) so an agent can check an identifier before using it.
• Equality & Comparison breakdown. Which mo:core modules expose a self-callable .equal (Text, Principal, Bool, Char, Blob) vs the x, y form (Nat, Int, Float, sized ints), and that == is compiler-generated structural equality while equal/compare are primarily implicit arguments for Map/Set/contains.
• do ? { ... } option-chaining construct (the counterpart to the M0064 misplaced-! fix above).

---

None of these are Caffeine-specific — they're general Motoko/moc correctness items. Happy to open a PR adding them to writing-motoko if that's easier than doing it yourselves. And if any are intentionally omitted, just let us know and we'll drop them on our side.

[marc0olo]

Checked this against commit 9274f9bb5d34 — nearly everything requested here has landed, thank you:

• ✅ writing-motoko: absolute "never send cycles" prohibition is Caffeine-draft-specific, not a general Motoko/IC constraint #1 EOP flag — new references/project-setup.md covers --default-persistent-actors, M0219/M0220, the persistent actor transitional form, and the -W style-warning flags.
• ✅ Keep core Motoko SKILL.md generic; isolate or drop Caffeine-specific guidance #2 error rows — M0220, M0218, M0064, M0145 all added to the table.
• ✅ writing-motoko: general Motoko items dropped vs prior coverage (persistence flags, M0220/M0141/M0064/M0145, Text.join/variant-paren pitfalls, reserved-keyword list, equality breakdown) #3 pitfalls — Text.join order ("Joining Text" section), variant tag parenthesization ("Variant Tag Arguments" section), and "never annotate lambda argument types" (extensive new section) are all in.
• ✅ migrating-motoko-actors: migration model reversed vs old skill (subset → full-signature); "no initializers" applied to all actors #4 reference material — references/reserved-keywords.md (full list), references/equality.md (the exact .equal/.compare receiver-vs-module breakdown asked for), and do ? { ... } in references/control-flow.md are all in.

The one item not addressed: M0141 (type/let declared before the actor body) still has no error-table row. Separately, the new "The Actor Must Come Last" section states that type/let declarations may precede the actor and only trailing declarations are invalid (which fails with M0096, not M0141) — so it's not clear M0141 in the sense we described (before the actor) is actually a real diagnostic in current moc. Could you confirm: is M0141 real and worth a row, or was our old skill's description of it simply wrong/outdated and this is already fully covered by the M0096 guidance? Either way, happy to close this out once you let us know.