chore(writing-motoko): sync caffeinelabs/skills 02e5316 → 6173cbc (null coalesce ??, break/continue)

[marc0olo]

Closes #349

Syncs writing-motoko from caffeinelabs/skills 02e5316 → 6173cbc (upstream version: 0.1.3 → 0.1.5). Only writing-motoko changed content upstream; migrating-motoko-actors and troubleshooting-motoko-migrations share the pinned commit and get a pin bump only.

What upstream added

• Null coalesce ?? for unwrap-or-default / unwrap-or-trap (opt ?? default, opt ?? Runtime.trap(...)), preferred over a two-arm switch that only peels ?T. Requires moc >= 1.7.0.
• Plain break / continue now documented as working inside for / while / loop — replacing the old (incorrect) claim that break is unsupported and requires labeled loops or a helper with early return.

Files changed

• skills/writing-motoko/SKILL.md — two new "ALWAYS use" bullets, new Null Coalesce (??) section, rewritten Option Handling, updated Common Operations line, best-practice Fix verified issues across 8 skills from multi-agent audit #4, and the control-flow Additional-References link.
• skills/writing-motoko/references/control-flow.md — restructured: ?? first, switch narrowed to variants/transforms, "Labeled Loops" replaced by Break and Continue.
• skills/writing-motoko/references/examples.md — createPost uses ?? Runtime.trap(...).
• .claude/upstream.md — all three caffeinelabs/skills entries pinned to 6173cbc, Last synced → 2026-08-12, writing-motoko upstream version → 0.1.5.
• evaluations/writing-motoko.json — +2 cases for the new behaviors.

icskills-owned sections

Preserved per .claude/upstream.md: frontmatter (our schema, tuned description), the mops-cli cross-ref rewrite, ## Additional References rename + mops tooling bullet, and references/ paths. No owned section is now covered by upstream, so none were dropped. compatibility unchanged — our floor moc >= 1.11.2 already exceeds the ?? requirement of 1.7.0.

Compiler verification

Validated the two new behaviors against moc directly (not just trusting the newer prose):

Test	moc 1.11.2	moc 1.6.0 (<1.7)
plain break / continue in a for loop	✅ clean	✅ clean
opt ?? 0	✅ clean	❌ M0001 syntax error

Confirms break/continue work and the ?? requires moc >= 1.7.0 note is accurate.

Known upstream defect (not patched locally)

Upstream added the working break/continue guidance but left a now-contradictory row in the Common Compile Error Patterns table:

| `unexpected token 'break'` | `break` reserved | Use helper function with early return |

Compiler-verified: plain break in a loop compiles fine; unexpected token 'break' only occurs when break is used as an identifier, whose correct fix is "rename the identifier" (not a helper). Our file matches upstream verbatim; per repo policy this is flagged upstream rather than diverged locally. Upstream issue: caffeinelabs/skills (linked once filed).

Evals

Added 2 cases (?? unwrap-or-trap; break/continue in loops), each run with baseline.

Eval results (with-skill vs baseline)

Null coalesce for unwrap-or-trap:  WITH 3/3 | WITHOUT 1/3
  WITHOUT: falls back to a two-arm switch to unwrap the option

break and continue in loops:       WITH 3/3 | WITHOUT 1/3
  WITHOUT: wraps the loop in `label done for (...)` and uses `break done` / `continue done`

npm run validate: all 27 skills pass (warnings only).

[github-actions]

Skill Validation Report

Validating skill: /home/runner/work/icskills/icskills/skills/writing-motoko

Structure

• Pass: SKILL.md found
• Pass: internal link: references/api-reference.md (exists)
• Pass: all files in references/ are referenced

Frontmatter

• Pass: name: "writing-motoko" (valid)
• Pass: description: (365 chars)
• Pass: license: "Apache-2.0"
• Pass: compatibility: (28 chars)
• Pass: metadata: (2 entries)

Tokens

• Warning: SKILL.md body is 8822 tokens (spec recommends < 5000)
• Warning: SKILL.md body is 705 lines (spec recommends < 500)

Markdown

• Pass: no unclosed code fences found

Tokens

File	Tokens
SKILL.md body	8,822
references/api-reference.md	9,901
references/control-flow.md	672
references/examples.md	4,528
references/type-conversions.md	417
Total	24,340

Content Analysis

Metric	Value
Word count	5,234
Code block ratio	0.35
Imperative ratio	0.15
Information density	0.25
Instruction specificity	0.87
Sections	37
List items	57
Code blocks	31

References Content Analysis

Metric	Value
Word count	8,504
Code block ratio	0.06
Imperative ratio	0.09
Information density	0.08
Instruction specificity	0.29
Sections	45
List items	456
Code blocks	24

Contamination Analysis

Metric	Value
Contamination level	low
Contamination score	0.00
Scope breadth	1

References Contamination Analysis

Metric	Value
Contamination level	medium
Contamination score	0.30
Scope breadth	0

• Multi-interface tool detected: stripe

Result: 2 warnings

Project Checks

✓ Project checks passed for 1 skills (0 warnings)