Problem
An agent writing Conway's Game of Life (the same agent whose feedback drove the Stage 11 primitives push — #463, #465, #466, #467, #470, #471) is hitting SKILL.md documentation gaps for features that work. The friction is now at the documentation layer, not the language layer.
Friction log, in order of surfacing:
-
Array literals not documented. Agent: "I don't see direct array literal syntax. I could use array_range(0, 0) to get an empty array, but that returns Array and I need Array. Looking more carefully at the skill documentation, I see [] is just an index operator, not an array literal."
- SKILL.md line 1625 lists
[] as a postfix index operator.
- Nowhere does it state that
[1, 2, 3] and [] are valid array literals.
examples/array_utilities.vera and every array-returning conformance test uses the literal syntax, but an agent reading only SKILL.md can't find it.
-
Closure outer-binding capture not documented. Agent: "closures seem to only reference their own parameters through De Bruijn indices, with no clear way to access outer bindings. Since the documentation doesn't explicitly cover closure capture semantics, I'll stick with recursion as the safer approach."
ch05_closures.vera in the conformance suite uses capture via higher De Bruijn indices.
- SKILL.md has a reference to closures only in the conformance-test table at line 2070 — no prose section explains the mechanics.
- Fallback to recursion is idiomatically correct but loses the array-combinator ergonomics the v0.0.117 work was supposed to unlock.
-
(Reserved for additional gaps the agent surfaces during this run.)
Scope
Small documentation-only PR — no code changes. Target SKILL.md sections:
- Add Array literals subsection (under "Composite types" or adjacent to "Array operations").
- Add Closures and captured bindings section (probably near "Iteration" or right before the Built-in Functions section, since closures are the mechanism
array_map/fold plug into).
- Audit pass: scan
tests/conformance/manifest.json for features that have conformance tests but no prose in SKILL.md.
- Every new subsection gets a worked
.vera example that compiles under scripts/check_skill_examples.py.
Why now
Empirical friction from a live agent run. Unlike ROADMAP priorities which are informed by benchmark results, this is the agent actively getting stuck right now. Documentation wins are the cheapest form of adoption improvement — one PR removes a wall for every future agent.
Not in scope
- No new built-ins.
- No code changes beyond docs asset regeneration.
- No spec/09 rewrites (closures are specified in Chapter 5).
Problem
An agent writing Conway's Game of Life (the same agent whose feedback drove the Stage 11 primitives push — #463, #465, #466, #467, #470, #471) is hitting SKILL.md documentation gaps for features that work. The friction is now at the documentation layer, not the language layer.
Friction log, in order of surfacing:
Array literals not documented. Agent: "I don't see direct array literal syntax. I could use array_range(0, 0) to get an empty array, but that returns Array and I need Array. Looking more carefully at the skill documentation, I see [] is just an index operator, not an array literal."
[]as a postfix index operator.[1, 2, 3]and[]are valid array literals.examples/array_utilities.veraand every array-returning conformance test uses the literal syntax, but an agent reading only SKILL.md can't find it.Closure outer-binding capture not documented. Agent: "closures seem to only reference their own parameters through De Bruijn indices, with no clear way to access outer bindings. Since the documentation doesn't explicitly cover closure capture semantics, I'll stick with recursion as the safer approach."
ch05_closures.verain the conformance suite uses capture via higher De Bruijn indices.(Reserved for additional gaps the agent surfaces during this run.)
Scope
Small documentation-only PR — no code changes. Target SKILL.md sections:
array_map/foldplug into).tests/conformance/manifest.jsonfor features that have conformance tests but no prose in SKILL.md..veraexample that compiles underscripts/check_skill_examples.py.Why now
Empirical friction from a live agent run. Unlike ROADMAP priorities which are informed by benchmark results, this is the agent actively getting stuck right now. Documentation wins are the cheapest form of adoption improvement — one PR removes a wall for every future agent.
Not in scope