[momentmaker]

Summary

Generated SVG no longer comes out flat and generic or takes several re-rolls. The new core skill svg generates premium, dimensional icons through a render-see-fix loop: it generates from a house-style token system, rasterizes its own output, inspects the render against a concrete rubric, patches, and converges. The two pains it removes are a missing style system (flat/generic) and a missing feedback loop (several tries), neither of which is a generation-horsepower problem.

It ships as a concrete, factorable icon loop. The generic "visual-convergence primitive" the brainstorm first imagined is deferred until a second consumer (charts/diagrams) constrains the interface, per AGENTS.md "don't build beyond the stage."

How it works

1. Read the brief into one token source (references/brief-schema.md, assets/tokens.json).
2. Loop: generate from tokens, rasterize with scripts/render.sh, inspect the rendered PNG against references/inspection-rubric.md, patch, re-render. Branch (a) stops when the render satisfies the brief (can fire on round 1). Branch (b) composes convergence-detect on the patch-set with its 3-round floor. A hard cap of 6 bounds the loop.
3. Finalize: optimize once after the loop, add accessibility by intent, validate path-only output.

The house-style system (references/house-style.md) is where premium comes from: a 24-keyline grid, procedural palette lanes, layered gradients, and a depth stack, with a flat to dimensional weight dial that scales only the depth.

Key decisions

See docs/decisions/2026-06-15-svg-visual-convergence.md.

• Concrete loop over a generic primitive. Three reviewers plus AGENTS.md flagged the primitive interface as premature with only one consumer. The loop is kept self-contained so it stays factorable.
• Two-branch stop. convergence-detect is a text-drift detector and cannot judge a render, so visual satisfaction is new in-skill logic (branch a, round-1 terminable); the patch-set drift check (branch b) reuses convergence-detect and its floor.
• Layered compositing, not feSpecularLighting alone. The single-filter claim was adversarially refuted in research; depth comes from stacking shadow, gradient, highlight, and bevel.
• Graceful degrade. No rasterizer means style-system-only output and a reported skip (exit 3 is a signal, not an error); the optimizer falls back to the unoptimized SVG and refuses to ship one whose viewBox or title it stripped.
• Falsifiable quality bar. A per-weight rubric, a kill-criterion (must beat single-shot ad-hoc or ship style-only), and a calibration gate against a labeled eval set.

Rich layout, permissions {bash: true, network: false, fs-write: scoped}, composes convergence-detect@^0.2.

Testing

• scripts/render.sh and scripts/optimize.sh tested directly: librsvg renders the dimensional bell to a 128x128 PNG; optimize runs svgo and preserves viewBox + title via a verify-and-fallback, never hard-failing; the no-rasterizer path returns exit 3.
• All 3 eval SVGs are well-formed; the dimensional bell rasterizes through the skill's own pipeline.
• Catalog regenerated via sitegen (48 skills), no drift on re-run.
• Code review (recall mode) on the scripts found and fixed 2 fallback-path bugs (cairosvg flag ambiguity, temp-file leak).

CI runs the full lint-skills (ajv schema-compile, SKILL.md presence, catalog-drift) and jutsu eval gates.

Known Residuals

Non-blocking, carried in the ADR:

1. Identity fit. This is the registry's first design-asset skill; reconfirm skills/core vs community/personal placement before tagging.
2. Arrow-inversion. If Quiver/Arrow ships as an agent-callable tool, the loop could become a commodity wrapper around a superior generator.
3. Calibration thresholds unset. The kill-criterion and agreement rate are filled when the eval first runs; until then the loop runs but its quality claim is provisional.
4. Repo-wide (out of scope here). CI does not validate any skill.yaml against the schema, and the Go loader skips shared/permissions/deps/trust. A maintainer may want a repo-level ajv-validate-skills step.

Post-Deploy Monitoring & Validation

No production or runtime impact: a markdown skill plus shell scripts plus a catalog regen. Validation is green CI (schema-compile, catalog-drift, jutsu eval), then jutsu install svg and generate a few real icons to confirm the loop and the degrade path behave. Per the AGENTS.md dogfood loop, run adversarial jutsu swarm pr-review before tagging.

---