Skip to content

SKILL.md missing sections: array literals + closure capture + audit pass #513

@aallan

Description

@aallan

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:

  1. 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.
  2. 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.
  3. (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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions