[rig-sampler] docs(rig): add JSDoc for p.var and p.region in PromptHelpers

[github-actions]

Samples run

Five consecutive samples were exercised through the stub runner (npm run sample):

Sample	Result	Repair turns	Notes
26-design-review.ts	✅ pass	0	s.enum("approve","revise","reject") worked cleanly in 1 turn
27-dependency-upgrade-plan.ts	✅ pass	0	risk: s.string is loose but caused no repair in the stub run
28-license-check.ts	✅ pass	0	p.bash + s.boolean + nested objects — all fine
29-bug-report-draft.ts	✅ pass	0	multi-field p.bash input, clean schema
30-github-action-review.ts	✅ pass	0	nested structured output, 1 turn

What the runs revealed

All five samples completed in a single turn with no repair loops — the schemas are well-matched to their tasks. The runs confirmed that s.enum (used in sample 26) prevents repair by constraining the decision field precisely.

Reading rig.ts after the runs highlighted a small documentation gap: the PromptHelpers interface fully documents every p.* helper except p.var and p.region, which were exported with no JSDoc at all. IDE hover, generated API docs, and SKILL.md examples all surface these helpers, but users hovering over them in an editor get no description, parameters, or @example.

Change

Added JSDoc to the var<T> and region signatures in the PromptHelpers interface in skills/rig/rig.ts:

• p.var(name, value) — explains the named binding concept, how the value is stored in PromptBuilder.vars, and when to use it vs plain interpolation.
• p.region(language, body) — explains fenced-block rendering, that PromptIntent/PromptBuilder values are resolved first, and shows the expansion in the @example.

No behaviour changes. All 228 unit tests pass; typecheck clean.

Generated by Daily Rig Sampler · sonnet46 86.9 AIC · ⌖ 8.02 AIC · ⊞ 5.4K · ◷

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs — requesting one change for a correctness issue in the p.var JSDoc.

📋 Key Themes & Highlights

Issue Found

• Misleading storage claim in p.var JSDoc: The description states the variable is "stored in PromptBuilder.vars", but p.var() (the PromptHelpers helper) only creates a PromptVariable object and returns it — it never touches any vars Map. The vars registration happens only via PromptBuilder.var(). The @example then shows builder.get("content") which would return undefined when the p.var() path is used inside p\...`template interpolation, since the template engine routes throughrenderPromptPart, not builder.var()`.

Positive Highlights

• ✅ p.region JSDoc is accurate — the description, note about PromptIntent/PromptBuilder pre-rendering, and @example expansion all match the implementation.
• ✅ Good initiative filling the documentation gap; the p.region addition is immediately useful.
• ✅ PR notes that all 228 tests pass and typecheck is clean.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · sonnet46 40.2 AIC · ⌖ 7.1 AIC · ⊞ 6.4K
_{Comment /matt to run again}

[github-actions]

[/grill-with-docs] The claim that p.var() stores in PromptBuilder.vars is inaccurate.

The JSDoc says "the name is stored in PromptBuilder.vars for later retrieval with .get(name)", but p.var() (the helper on line 1072–1074) only calls createPromptVariable and returns — it never writes to any vars map. That storage only happens in PromptBuilder.var() (line 1101). Crucially, when p.var(...) is used inside a p\...`template interpolation, the engine callsbuilder.write(value)→renderPromptPart, which handles PromptVariableby rendering its value directly —builder.var()is never called, so the variable is never registered in.vars. The @example's builder.get("content")call would returnundefined` in that pattern.

💡 Suggested correction

/**
 * Creates a named prompt variable binding. When used inside a `p\`...\`` template
 * interpolation the value is rendered inline. To also register the variable for
 * later retrieval, call `builder.var(name, value)` directly on a `PromptBuilder`
 * instance — the template tag's `write()` path does not invoke `builder.var()`.
 *
 * `@example`
 * // Register and retrieve via PromptBuilder:
 * const builder = p();
 * builder.var("content", p.read("README.md"));
 * builder.write(`Summarize: `, builder.get("content"));
 * // builder.get("content") returns the PromptIntent for README.md
 *
 * // Or use inline (no retrieval):
 * const prompt = p`Summarize: ${p.var("content", p.read("README.md"))}`;
 */