From 57d94a8ff8b6e852c8de1ca01dae32d079767fc1 Mon Sep 17 00:00:00 2001
From: Dylan Thomas <dvhthomas@gmail.com>
Date: Thu, 12 Mar 2026 18:34:54 -0600
Subject: [PATCH] docs: add pitfalls section and grant Edit tool access

Add Common Pitfalls covering immutable variables, unit propagation,
and NL-first guidance. Grant Edit tool access in SKILL.md so agents
can fix .cm files incrementally.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CALCMARK-AGENT.md                             | 40 +++++++++++++++++++
 .../.claude/skills/calcmark/SKILL.md          |  8 +++-
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/CALCMARK-AGENT.md b/CALCMARK-AGENT.md
index b5e4ce3..fe4496e 100644
--- a/CALCMARK-AGENT.md
+++ b/CALCMARK-AGENT.md
@@ -85,6 +85,46 @@ Array of blocks (`"calculation"` or `"text"`). Each calculation result has: `sou
 **Errors** go to stderr (not JSON). Check exit code.
 **Silent misinterpretation**: if output has `"type": "text"` where you expected calculations, the expression was treated as prose.
 
+## Common Pitfalls
+
+### Variables Are Immutable
+
+Variables cannot be reassigned within a document. This will error:
+
+```calcmark
+x = 10
+x = 20   # ERROR: cannot reassign 'x'
+```
+
+Use distinct variable names for each calculation step.
+
+### Unit Propagation
+
+Arithmetic preserves the numerator's unit. Raw division can produce unexpected units:
+
+```calcmark
+customers = 343 customers
+servers_raw = customers / 10   # Result: 34.3 customers (NOT servers!)
+```
+
+Use the NL `capacity` form instead:
+
+```calcmark
+servers = 343 customers at 10 customers per server   # Result: 35 server ✓
+```
+
+### Prefer NL Forms Over Raw Arithmetic
+
+Built-in NL functions handle rounding, units, and edge cases. Run `cm help functions` to see all available forms. Key examples:
+
+- **Capacity**: `demand at cap per unit` instead of manual division
+- **Growth**: `compound P by R over T` or `grow S by X over N` instead of manual formulas
+- **Rates**: `rate over duration` instead of manual multiplication
+
+### Error Output Goes to stderr
+
+Errors are plain text on stderr, not JSON. Always check the exit code before parsing output as JSON.
+
 ## Security
 
 - Ask the user before installing `cm`
diff --git a/platforms/claude-code/.claude/skills/calcmark/SKILL.md b/platforms/claude-code/.claude/skills/calcmark/SKILL.md
index 20fac6a..28749f5 100644
--- a/platforms/claude-code/.claude/skills/calcmark/SKILL.md
+++ b/platforms/claude-code/.claude/skills/calcmark/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: calcmark
 description: Use CalcMark to perform calculations, create computational documents, and produce analysis artifacts (.cm files, HTML, JSON, Markdown). Activate when the user needs cost modeling, capacity planning, unit conversions, date arithmetic, napkin math, or any quantitative analysis.
-allowed-tools: Bash(cm:*), Bash(brew:*), Bash(which:*), Bash(uname:*), Bash(curl:*), Read, Write, WebFetch
+allowed-tools: Bash(cm:*), Bash(brew:*), Bash(which:*), Bash(uname:*), Bash(curl:*), Read, Write, Edit, WebFetch
 ---
 
 # CalcMark Agent Skill
@@ -80,6 +80,12 @@ transfer 500 KB across regional gigabit               # network transfer
 2. **Research artifact**: write `.cm` file, `cm eval` for JSON evidence
 3. **Document deliverable**: write `.cm` with `{{templates}}`, `cm convert --to=html`
 
+### Common Pitfalls
+
+- **Variables are immutable** — you cannot reassign a variable. Use distinct names for each step.
+- **Unit propagation** — `customers / 10` keeps the `customers` unit. Use NL forms like `343 customers at 10 customers per server` for correct unit handling.
+- **Prefer NL forms** — use `capacity`, `compound`, `grow`, and other NL functions instead of raw arithmetic. Run `cm help functions` to discover them.
+
 ### Error Handling
 
 - Errors go to **stderr** (not JSON). Check exit code.