diff --git a/hermes/design/visualize/SKILL.md b/hermes/design/visualize/SKILL.md index 0be1122..34e30b0 100644 --- a/hermes/design/visualize/SKILL.md +++ b/hermes/design/visualize/SKILL.md @@ -26,20 +26,12 @@ allowed-tools: - Bash(bash */visualize/scripts/publish.sh*) - Bash(*/visualize/scripts/publish.sh*) description: > - Generate beautiful, on-brand HTML artifacts — reports, diagrams, diff - reviews, slide decks, plans, recaps, dashboards. Loads on creation - intents ("create a plan", "make me an implementation plan", - "generate a diagram", "build a slide deck", "draft a recap", - "visualize this", "render this as HTML", "make me a status update") - and exploration intents ("show me three layouts", "explore document - shapes", "compare visual treatments", "explore a new design system", - "compare replacement brand directions") and iteration intents ("make this beautiful", "polish this report", - "make this less generic", "design this", "theme this", "use my - brand", "iterate on this design", "review this artifact", "make - this bolder", "make this quieter", "simplify this design", - "animate this", "improve the look of", "give this a refresh"). - Captures brand from the user's codebase, asking, or live site, then - applies it to every artifact. + Create, explore, refine, and review on-brand HTML reports, diagrams, + diff reviews, slide decks, plans, recaps, and dashboards. Use to visualize + information, compare layouts or design systems, apply a brand or theme, + or improve an artifact's design, including simplifying, polishing, making + it bolder or quieter, and animating. Capture brand from code, conversation, + or a live site. --- # visualize — beautiful, on-brand HTML artifacts @@ -48,25 +40,21 @@ Generate self-contained HTML artifacts composed from `templates/*/template.md` c ## Design judgment -Identify what the reader needs to understand, make the important distinction visible, and retain the evidence and qualifications needed to interpret it correctly. +Identify the reader's task and make the important distinction visible, retaining the evidence and qualifications needed to interpret it. Before choosing a treatment, find the source's organizing relationship, contrast, sequence, decision, or object; let it shape the opening, section rhythm, and explanatory primitives. When none helps, prefer restrained reading over a manufactured organizing idea. -Find the artifact's organizing idea before choosing its visual treatment. Look for a relationship, contrast, sequence, decision, or object in the source that the composition itself can make easier to understand. Use that idea to shape the opening, section rhythm, and any explanatory primitive. When the source has no useful spatial or structural idea, prefer a restrained reading experience over manufacturing one. - -Artifact mode describes how the reader consumes the information, not the aesthetic family it must use. A document can use product-native, application-like, spatial, editorial, or technical-drawing grammar when that grammar serves the source, reader, and brand. Do not equate `document` with editorial publishing, or `canvas` with diagram chrome. - -Visual conviction can come from composition, typography, density, spatial rhythm, imagery, interaction, or color. Do not add hues, decoration, or components merely to make an artifact feel designed. A restrained palette can carry a strong point of view when another dimension does the expressive work. +Artifact mode describes consumption, not aesthetics: `document` need not mean editorial publishing, nor `canvas` diagram chrome. Composition, typography, density, spatial rhythm, imagery, interaction, or color can supply conviction. Do not add hues, decoration, or components merely to make the artifact feel designed. Before responding to feedback, compare the observation with the artifact's reader, purpose, source, and approved brief where one exists. Distinguish an implementation defect, a design that fails its existing requirements, and evidence that a requirement or assumption has changed. The current composition is a solution, not a constraint. Make authorized corrections within the existing brief directly. If feedback implies a change to established requirements that the user has not already approved, explain the proposed change and obtain agreement before editing. When several structural or visual directions remain plausible, recommend `explore artifact` within its supported scope. When the direction is established, use the ordinary creation or refinement workflow. Follow that workflow's approval requirements; a small correction does not need a new exploration. -Evaluate proposed fixes together against the reader's task. Do not turn every critique finding into an addition or treat a small diff as evidence that the direction is sound. Preserve decision-relevant deferred observations in existing review or task notes. +Judge proposed fixes together against the reader's task. Do not turn every critique finding into an addition or treat a small diff as evidence of a sound direction. Retain decision-relevant deferred observations in existing review or task notes. ## Commands -`/visualize` invokes the skill. The argument tells the agent what to do. +`/visualize` takes a command or topic/path. -**Default (no command, or the first argument is a topic):** `/visualize ` creates a new artifact. The agent picks a template from intent across all of `templates/`, composes against the resolved project or artifact-theme context, writes self-contained HTML. **The flow is gated:** preflight checklist + shape-gate before code, no self-authored briefs. See `reference/create.md`. +**Default (topic/path without a command):** create self-contained HTML using a template and resolved context. Read `reference/create.md`; preflight and user-approved shape precede code. An agent-authored brief cannot approve itself. **Named commands:** @@ -82,12 +70,12 @@ Evaluate proposed fixes together against the reader's task. Do not turn every cr | **Evaluate** | `review` | `` | Deterministic detector findings + LLM judgment. Reports; doesn't modify the file. | `reference/review.md` | | **Publish** | `publish` | `` | Push the artifact to display.dev via MCP / CLI / HTTP cascade. | `reference/publish.md` | -Invocation forms: `/visualize teach`, `/visualize explore artifact ./report.html`, `/visualize polish ./report.html`, `/visualize publish ./diagram.html`. On hosts without a slash-command form, the skill loads on intent-match from the description above; natural-language is the primary entry there. +Example: `/visualize polish ./report.html`. On hosts without slash commands, natural-language intent is the primary entry. ## Routing rules 1. **No argument**: render the Commands table above as the user-facing menu, grouped by category. Ask what they'd like to do. -2. **First word matches a command**: **load its reference file before doing anything else.** Non-negotiable — the table row + this section is insufficient; the procedure lives in the reference. Everything after the command name is the target. +2. **First word matches a command**: **load its reference before acting**; the table is not the procedure. Everything after the command name is the target. 3. **Natural-language intent**: requests to compare design alternatives load `reference/explore.md`; capturing or reconciling project identity loads `reference/teach.md`. Otherwise load `reference/create.md` for creation or an explicitly requested restyling of an existing artifact. A named theme follows Artifact themes below; it does not require an exploration round. 4. **Relationship-diagram route during creation**: when preflight first identifies a likely relationship diagram, load `reference/diagram.md` and the one tentative non-spatial type reference needed for that figure before presenting the shape gate. For multi-figure artifacts, load one reference for each distinct tentative family: `reference/diagram-flow.md`, `reference/diagram-system.md`, `reference/diagram-sequence.md`, `reference/diagram-state.md`, or `reference/diagram-hierarchy.md`. Spatial figures use `reference/diagram.md` alone. If approval changes a figure's type, load the replacement reference before authoring; do not load unrelated families. 5. **Generated-image route during creation**: when the approved shape requires generated bitmap imagery, load `reference/image-generation.md` before selecting or invoking a route. Use only the active callable inventory or an explicitly selected API adapter. Never infer a route from a key, executable, mount, or model claim, and never retry or fall back after an ambiguous attempt. @@ -95,25 +83,18 @@ Invocation forms: `/visualize teach`, `/visualize explore artifact ./report.html ## Hand-off output shape -After a refine verb (`simplify` / `bolder` / `quieter` / `animate`) finishes its run, summarise to the user in plain markdown. Don't render the summary as a fenced code block — it's conversational output, not machine-readable. Vary phrasing across runs; pick wording per context (engineer reading detector output vs. designer iterating on a brand brief). `polish` has its own output shape — see `reference/polish.md`. - -Every refine run's summary covers four facts: - -- Which verb ran, against which artifact. -- What the verb actually did. Pull the verb-specific content from the per-verb reference's "what to surface" list (focal moment, cuts + audit trail, strategy, what stayed, hero moment, reduced-motion handling — depends on the verb). -- Diff size as a percent of the artifact. -- Which next action makes sense, if any. Polish is the default next step from a successful refine run. - -Variant rules (behaviour, not surface text): +After `simplify` / `bolder` / `quieter` / `animate`, report in conversational markdown: verb and target, changes drawn from the reference's "what to surface" list, diff percentage, and the appropriate next action. Successful refinement defaults to `polish`, which has its own output shape in `reference/polish.md`. -- **Context source note.** If the run cannot use a persisted `DESIGN.md` / `PRODUCT.md`, mention once which fallback source anchored the work: project instructions, README/docs, generated seed, or Clean defaults. Also nudge the user to run `/visualize teach` so that fallback can become a real brand profile. Clean defaults are the last resort after the Brand profile rules below find no usable project guidance. -- **Diff exceeded the 40% guard.** Stop refinement and report the affected scope. Apply Design judgment to recommend exploration when the structural direction remains unresolved, or a fresh creation pass when it is established. Do not continue into polish. -- **Verb shouldn't have run** (Absolute bans present, no decoration to remove, no focal moment, etc.). Skip the standard run summary entirely. Surface a short refusal that names the reason and routes to the right alternative verb. Each per-verb reference's "When `` is the right verb (and when it isn't)" section enumerates the verb's specific refusal conditions. +Variant rules: -Tone is conversational. Lead with what changed, not with a banner. Don't capitalise words for emphasis. Don't print a ` pass complete ·` header — the summary's content is the proof of completion. +- **Fallback context:** name the source once (project instructions, README/docs, seed, or Clean) and nudge `/visualize teach`. Follow Brand profile's fallback hierarchy. +- **Diff >40%:** stop, report the scope, and apply Design judgment to recommend exploration if direction is unresolved or fresh creation if established. Do not continue to polish. +- **Verb shouldn't have run:** use the reference's refusal conditions; replace the standard summary with a short reason and the appropriate alternative. For `animate` specifically: when the brand declares `motion: none`, a fifth variant applies — see `reference/animate.md`. +Lead with changes, vary phrasing for the reader, and avoid fenced summaries, capitalized emphasis, or ` pass complete ·` banners. + ## Absolute bans Match-and-refuse. Apply on every command and the default creation flow. These ban specific patterns — not aesthetics, not registers. A brand can declare a font, a hue, or a layout that looks unusual; it cannot redeem any of these patterns by declaring them as identity. An explicit `.visualize-detect.json` skip can waive only a detector-backed ban with a concrete rule ID; it is project policy, not runtime brand suppression, and cannot waive a Layer-2 ban. @@ -191,21 +172,30 @@ These are not brand aesthetics; they are observed model reflexes with required c ## AI slop test (two altitudes) -Run both. The second catches what the first misses. +Run both tests: -**First-order**: if someone could guess the template + palette from the topic alone, you've hit the first training-data reflex. Topic stereotypes are prompts to inspect the brief, not color prohibitions: red, purple gradients, or navy-and-gold can fit a specific artifact. Rework unsupported defaults, not approved identity. +- **First-order:** could the topic alone predict the template and palette? Inspect unsupported stereotypes, not approved identity; hue names are not prohibitions. +- **Second-order:** could topic plus anti-references predict the aesthetic family? Avoid substituting another saturated reflex, such as cream/Georgia/margin-note editorial, mono/grid/heavy-border terminal, or uppercase/grotesk/grid Swiss-poster when the source and register do not support it. -**Second-order**: if someone could guess the aesthetic family from topic-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic," "fintech that's not navy-and-gold → terminal-native dark mode"), the second-tier reflex isn't avoided. Currently-saturated families to watch for: editorial-Tufte clone (cream + Georgia + side-margin notes when the topic isn't editorial), brutalist-terminal clone (mono + grid + heavy borders when the topic isn't dev-tool), Swiss-poster clone (uppercase + grotesk + grid when the topic isn't presentation). Rework until both altitudes return "no, you couldn't have guessed." +Rework unsupported defaults until neither test predicts the treatment; preserve approved identity. ## Brand profile -Every render reads available `DESIGN.md` (visual identity + design tokens) and `PRODUCT.md` (voice, audience, tone) at the project root. `teach` derives custom design tokens for the brand and writes them in `DESIGN.md` as YAML frontmatter (the Google Stitch canonical format: machine-readable tokens) plus a six-section markdown body (Overview / Colors / Typography / Elevation / Components / Do's and Don'ts), with a sidecar `tokens.css` at the project root carrying the CSS-form tokens templates read at render time. Project profiles retain concrete tokens, not a `theme: ` pointer. +Every render reads available project-root `DESIGN.md` (visual identity/tokens), `PRODUCT.md` (voice/audience/tone), and `tokens.css`. `teach` writes concrete project tokens in Stitch-format `DESIGN.md` plus the CSS sidecar, not a `theme: ` pointer; its schema and derivation procedure live in `reference/teach.md`. + +**Authority:** persisted `DESIGN.md` and `tokens.css` own visual tokens; `PRODUCT.md` owns voice and audience. Project instructions fill gaps without overriding persisted tokens unless the user explicitly says otherwise in the current request. Apply Artifact themes' approved exceptions before locking context. Brand authority is identity-scoped. If the request fixes a named identity but the resolved project profile clearly belongs to another product, do not substitute, relabel, or approximate it. Stop before the shape gate or any artifact edit and request matching authority or explicit permission for an artifact-only override. -The design systems under `design-systems/` are reference packages with design guidance, tokens, and previews. `teach` and System Explore read them when deriving project identities; artifact creation and exploration can use them as themes under the shared contract below. +`design-systems/` packages supply guidance, tokens, and previews for `teach`, System Explore, and artifact themes. + +**Fallback when no DESIGN.md exists:** + +1. Preserve an approved artifact reference as the baseline where project guidance is absent; do not replace it with a seed or Clean. +2. Otherwise read available project instructions (`AGENTS.md`, `CLAUDE.md`, README, docs) for positioning, visual direction, anti-references, and design principles. Treat usable guidance as binding brand context, including named fonts, palette roles, logo/mark rules, density/register, and anti-references, not optional mood. Follow referenced tokens, stylesheets, logo components, and guidelines before approximating from prose. Named fonts and palette roles override Clean's values; anti-references rule out the corresponding fallback register. Clean supplies the semantic token surface, not its fonts, monochrome palette, or warm/cream defaults. +3. Only with no usable visual direction, run `node $SKILL_DIR/scripts/palette.mjs --from ""`. Compose temporary primary, background, foreground, accent, chart, and state tokens from the seed and brief, using its `derived` contrast numbers, chroma budgets, and light/dark ladders. Do not estimate those values or copy Clean unchanged. If the seed fights the brief, re-run with `--not ` or `--vary ` and note the veto in the shape gate. Validate composed tokens with `node $SKILL_DIR/scripts/palette.mjs --check --strict`; fix errors (exit 2) before render. -**Fallback when no DESIGN.md exists:** an approved artifact reference supplies the visual baseline where project guidance is absent; do not replace it with a seed or Clean defaults. Otherwise, first read available project instructions (`AGENTS.md`, `CLAUDE.md`, README, docs) for product positioning, visual direction, anti-references, and design principles. If those files contain usable brand/design guidance, treat it as binding brand context while using Clean's token **surface** as the structural floor. Explicit cues in repo guidance override Clean values: named fonts become the artifact font stack, named palette roles become the artifact color tokens, and named anti-references rule out the corresponding fallback register. If the guidance points at concrete token files, stylesheet files, logo components, or design guidelines, read those referenced files and use their values before approximating from prose. Using Clean's token surface means keeping the semantic variable shape, not copying Clean's fonts, monochrome values, or warm/cream defaults. Only run `node $SKILL_DIR/scripts/palette.mjs --from ""` when the project has no usable visual direction at all. When a seed is used, compose the temporary `--primary`, `--background`, `--foreground`, `--accent`, chart, and state tokens from the seed + artifact brief; do not copy Clean's monochrome palette unchanged. Use the script's `derived` block (real contrast numbers, per-hue chroma budgets, light + dark lightness ladders) instead of estimating those values; if the seed's register fights the brief, re-run with `--not ` or `--vary ` and note the veto in the shape gate. After composing, validate with `node $SKILL_DIR/scripts/palette.mjs --check --strict` and fix error findings (exit 2) before render. Nudge `/visualize teach` once per session so repo guidance or the temporary seed can become a real brand profile. +Nudge `/visualize teach` once per session when using fallback context. **Refine verbs on missing persisted brand files:** `simplify` / `bolder` / `quieter` / `animate` / `polish` use the same fallback hierarchy as creation. Project instructions, README/docs, or other already-loaded context can be a valid qualitative brand anchor. Clean defaults are only the anchor when no usable project guidance exists. Whenever a fallback source is used, mention that source once and nudge `/visualize teach` so the fallback can become a real brand profile. @@ -213,15 +203,15 @@ The design systems under `design-systems/` are reference packages with design gu ## Artifact themes -A theme is a reference design system applied to one artifact, not a new stored object or a project-wide adoption. Use the current project system by default. Resolve binding project choices, approved artifact exceptions, and open design dimensions before borrowing from a reference. A named reference or a request to make an artifact more expressive does not silently override binding project choices; clarify conflicts that the request leaves unresolved. Explicit permission to replace visual styling applies only to the named artifact and dimensions. Do not invent constraints where the project is silent. +A theme is a reference design system applied to one artifact, not a new stored object or a project-wide adoption. Default to the project system; resolve binding choices, approved exceptions, and open dimensions before borrowing. A named reference or request for more expression does not silently override binding choices. Clarify unresolved conflicts; explicit replacement permission covers only the named artifact and dimensions. Do not invent constraints where the project is silent. -Read the selected `design-systems//README.md` when present, then its `DESIGN.md` and `tokens.css`. README is the package entry point; DESIGN owns suitability, identity, and adaptation guidance. Use previews to understand the treatment, not as required layouts. If the user wants alternatives, propose a small relevant shortlist rather than loading the entire catalog. A missing README does not make a package unavailable. +Read the selected package's `README.md` when present, then `DESIGN.md` and `tokens.css`. DESIGN owns suitability, identity, and adaptation. Previews illustrate treatment, not required layouts. When the user wants alternatives, offer a small relevant shortlist; do not load the whole catalog. A missing README does not make a package unavailable. -Apply a named treatment through ordinary creation or revision; compare unresolved treatments through `explore artifact`. Neither requires a new layout or a project profile first. For new content, derive structure from the reader's task and source. For existing artifacts, preserve content, order, assets, and behavior unless those changes were requested. A broad restyling uses `reference/create.md` with that preservation scope, not a narrow refine verb forced past its diff guard. Existing approval gates still apply; an explicit request already covering the proposed changes does not need reconfirmation. +Apply a treatment through creation or revision; compare unresolved treatments through `explore artifact`. Neither requires a new layout or project profile. Derive new structure from source and reader task. Preserve existing content, order, assets, and behavior unless changes were requested. Broad restyling uses `reference/create.md` with that scope rather than exceeding a refine verb's diff guard. Existing approval gates apply; an explicit request covering the proposed changes needs no reconfirmation. -Translate the reference's hierarchy, spacing, surfaces, and component treatment as well as its palette and type. Keep non-overridden project choices. Embed the resolved tokens, including designed light/dark and OS-dark behavior, in the artifact; do not replace the project's token source. Verify against the resolved artifact context, not the overridden project values. Describe partial borrowing and retained constraints rather than claiming an unchanged reference application. Keep the approved exception and its scope in existing task notes or a short artifact comment so later refinement can preserve it; unexplained styling drift alone is not approval. +Translate hierarchy, spacing, surfaces, and component treatment alongside palette and type. Preserve non-overridden project choices. Embed resolved tokens with light, explicit-dark, and OS-dark behavior in the artifact; do not replace the project's token source. Verify against the resolved artifact context, not overridden values. Describe partial borrowing and retained constraints accurately. Record approved exceptions and scope in existing task notes or a short artifact comment for later refinement; unexplained drift is not approval. -For project-wide capture or direct derivation, use `teach`. To compare new or explicitly requested replacement systems, use `explore system`. Neither route is a prerequisite for artifact themes. +Project-wide capture or derivation uses `teach`; comparing new or explicitly requested replacement systems uses `explore system`. Neither is a prerequisite for artifact themes. ## Universal laws diff --git a/hermes/design/visualize/reference/create.md b/hermes/design/visualize/reference/create.md index b163aa4..b8d194b 100644 --- a/hermes/design/visualize/reference/create.md +++ b/hermes/design/visualize/reference/create.md @@ -10,7 +10,7 @@ Autonomous harnesses (Codex-class) have been observed jumping to file writes bef Before composing, confirm: -1. **Context loaded.** Resolve artifact context, brand/context source, token source, and fallback behavior per SKILL.md before choosing a template or writing code. If fallback context is used because `DESIGN.md` / `PRODUCT.md` are absent, extract binding brand cues from project instructions: named fonts, palette roles, logo/mark rules, density/register, and anti-references. If those instructions cite token files, stylesheets, design guidelines, or logo components, read those files before composing. Do not treat those cues as optional mood. **Brand-source precedence when sources disagree:** persisted `DESIGN.md` and `tokens.css` win for visual tokens (colors, fonts, surfaces); `PRODUCT.md` wins for voice and audience; fallback project instructions fill gaps but do not override persisted brand tokens unless the user explicitly says so in the current request. Apply SKILL.md's Artifact themes contract before locking the visual context; approved artifact exceptions participate in that resolution. +1. **Context loaded.** Resolve context and tokens using SKILL.md's Brand profile and Artifact themes contracts, including fallback sources, their referenced assets, and approved exceptions, before choosing a template or writing code. 2. **Brand-fidelity lock.** From the artifact context resolved in step 1, record the applicable invariants across the categories below. These are enforceable, not aspirational. Do not invent invariants where the brand profile is silent — absence is a valid answer for any individual category. - **Named fonts.** If the brand profile or fallback source names specific fonts, those fonts must lead the body / heading / code CSS stacks in the artifact. `system-ui`, `Inter`, `-apple-system`, or any other generic sans cannot lead the stack unless the brand explicitly names them. - **Named palette / color system.** If the brand profile names palette roles or uses a specific color system (OKLCH, `color-mix`, `lab`, `lch`), `--background` / `--foreground` / `--primary` / borders / surfaces must derive from that palette and use that color system, not from fallback cream-paper, generic grays, or seed-generated hues. @@ -25,7 +25,7 @@ Before composing, confirm: - `deck` — slide or presentation sequence where each screen is consumed separately. Mode describes consumption, not aesthetic register. A `document` can still use product-native, application-like, spatial, editorial, or technical-drawing grammar when that grammar expresses the source and brand. Do not let the conservative mode default choose the artifact's look for you. -5. **Template picked.** Select from `templates/*/template.md` using template name, description, Use when, and Do not use when. Templates are starting points, not fixed artifact shells: customize the chosen template to fit the reader job and source, then fall back to pattern recipes for recurring structures the template does not cover. Template names are weak evidence; required structure and reader job are strong evidence. Pick the most specific template only when its required structure fits the source without inventing missing fields. If a named template would force a time axis, live-status semantics, escalation path, operational checks, slide sequence, scoring model, or other content the source does not provide, choose the broader document template and borrow only bounded primitives. Bounded primitives are small structures inside the chosen mode — e.g. labeled time-window rows, status marks, compact scenario tables, one contained topology figure — not the named template's full chrome or layout system. State the choice with one-line rationale. +5. **Template picked.** Start candidate selection from the name, description, Use when, and Do not use when sections of `templates/*/template.md`. Read further candidate sections only when needed to resolve uncertainty about structural fit. Templates are starting points, not fixed artifact shells: customize the chosen template to fit the reader job and source, then fall back to pattern recipes for recurring structures the template does not cover. Template names are weak evidence; required structure and reader job are strong evidence. Pick the most specific template only when its required structure fits the source without inventing missing fields. If a named template would force a time axis, live-status semantics, escalation path, operational checks, slide sequence, scoring model, or other content the source does not provide, choose the broader document template and borrow only bounded primitives. Bounded primitives are small structures inside the chosen mode — e.g. labeled time-window rows, status marks, compact scenario tables, one contained topology figure — not the named template's full chrome or layout system. State the choice with one-line rationale. 6. **Composition reflex check.** Before sketching shape, name up to three artifact-class defaults you must NOT assume — at least one when an obvious reflex exists for the class. The defaults are moves that appear across every AI-generated version of this artifact class regardless of source or brand — the median answer to the class's prompt. The reflex defaults for any artifact class tend to cluster around the dominant masthead pattern, the default section rhythm, the default verdict/answer placement, and the default secondary-navigation device (TOC, sidebar, sticky chrome). Identify the ones that apply to the class at hand (up to three). diff --git a/hermes/design/visualize/reference/polish.md b/hermes/design/visualize/reference/polish.md index 2b17d2c..ce80dea 100644 --- a/hermes/design/visualize/reference/polish.md +++ b/hermes/design/visualize/reference/polish.md @@ -11,7 +11,7 @@ Walk every applicable quality dimension and report findings against the reader's Read in order: 1. **The artifact.** Open the file, scroll it end-to-end in your head. Notice what the eye lands on first, what feels off, what reads as "agent eyeballed it." -2. **The detector.** Run `node $SKILL_DIR/scripts/detect.mjs --json ` for the mechanical floor. Detector output is **defect-evidence**, never **done-evidence** — a clean result is not proof the artifact is strong. The detector catches what regex can identify; polish covers everything else. +2. **The detector.** Run `node $SKILL_DIR/scripts/detect.mjs --json ` for the mechanical floor; apply SKILL.md's Universal law 7 when interpreting the result. ## Discovery: name the root cause, not just the symptom @@ -170,7 +170,7 @@ Skipped verification accumulates as "polish reports clean but the artifact is br If the artifact needs broad rework, polish has misfired. The escape: -- **Artifact carries ≥3 Absolute bans** → refuse and route to `/visualize simplify` first. Simplify's job is removing ban patterns; polish assumes a clean baseline. (SKILL.md's "Refine verbs on artifacts that carry ≥3 Absolute bans" rule applies.) +- **Ban-heavy artifact** → apply SKILL.md's "Refine verbs on artifacts that carry ≥3 Absolute bans" refusal and routing contract. - **Artifact needs broad rework beyond polish** → stop refinement and apply SKILL.md's Hand-off output shape and Design judgment to recommend the next action. - **Do not hand off to another Refine verb expecting it to come back.** The Refine verbs (`simplify` / `bolder` / `quieter` / `animate`) hand off to polish, but polish doesn't hand off to them — that creates a cycle. When polish refuses, recommend the next action to the user; do not start another command. diff --git a/hermes/design/visualize/reference/review.md b/hermes/design/visualize/reference/review.md index cdc3f78..6ba6c9e 100644 --- a/hermes/design/visualize/reference/review.md +++ b/hermes/design/visualize/reference/review.md @@ -92,8 +92,7 @@ Things detect.mjs deliberately doesn't try to catch: register-dependence, vocab- - **Mock identity** beyond the obvious: fictitious customer quotes ("Sarah Johnson, VP Marketing"), placeholder phone / address / company / brand names that aren't in the obvious set (Acme, Globex, Anytown, TBD, XXX-XXX-XXXX). - **Slop openers**: "leverage / streamline / empower / unlock / elevate / unleash / robust / holistic / seamless / cutting-edge / next-gen / In conclusion / TL;DR:" packed into the opening paragraphs. -- **Sycophant footers**: "I hope you find this useful", "Happy to clarify", "Hopefully this addresses your needs", "Best, Claude", anything signed by an AI. -- **Imperative tricolon** ("Ship faster. Build smarter. Scale forever."): three commands ending in periods, regardless of content. Can't be redeemed. +- **Sycophant footers and imperative tricolons**: inspect against SKILL.md BAN 7 and BAN 6. **Brand- and register-dependent slop** (mechanical detector would false-positive). These judgment calls exclude SKILL.md's Absolute bans, which resolved context cannot redeem. When deciding the remaining calls, consult [color.md](color.md) / [typography.md](typography.md) / [spatial.md](spatial.md) / [copy.md](copy.md) for the deeper material: @@ -161,7 +160,7 @@ Context-suppressed detector results are audit evidence rather than actionable fi - **≥4 `slop/center-everything` declarations in a non-Bauhaus / non-academic register = pattern.** Single centered hero is fine. When unsure, default to surfacing it as info + naming the aggregate count. -- **Universal law 6**: the reader is the judge. Does each finding make the reader's job harder, or just satisfy a rule? +- Apply SKILL.md's Universal law 6 to every finding. ## Output format (mandatory shape) diff --git a/hermes/design/visualize/templates/comparison/template.md b/hermes/design/visualize/templates/comparison/template.md index 8ca488c..5afa071 100644 --- a/hermes/design/visualize/templates/comparison/template.md +++ b/hermes/design/visualize/templates/comparison/template.md @@ -1,17 +1,17 @@ --- name: Comparison -description: A decision-support artifact for comparing options, tradeoffs, and recommendations. +description: A qualitative options matrix with yes/no/partial/varies cell states, supporting values, and tradeoffs. --- # Comparison ## Use when -Use this template when the reader needs decision-support artifact for comparing options, tradeoffs, and recommendations. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use for one option-by-criterion matrix. Every cell carries both a state (`yes` / `no` / `partial` / `varies`) and a supporting value; explanations carry nuance. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +For numeric observations without an option-by-criterion evaluation, use Report with an ordinary table. Split multiple comparison matrices into separate artifacts or use Report with embedded comparison figures. ## Structure @@ -37,9 +37,9 @@ The first two phone screens must deliver title, thesis, and essential context wi ## Failure modes -**Single-table rule.** Exactly one `` per artifact. A second `cmp-table` block trips the detector — multi-table comparisons fragment the read; split them into multiple Comparison artifacts or fold into a Report with embedded comparison figures. +**Single-table rule.** Render the matrix as `
`. A second `cmp-table` block trips the detector because multi-table comparisons fragment the read. -**Cell-state vocabulary is closed.** States are drawn from `yes` / `no` / `partial` / `varies` — full stop. Inventing new states (`coming-soon`, `beta`, `enterprise-only`) trips the detector because they erode the scan-at-a-glance property the closed vocabulary buys. Encode nuance in the cell's `detail` text, not in a new state. Every cell carries both a `state` and a `value`; a blank cell is a content gap, not a styling choice. +**Invalid cell states.** Inventing states (`coming-soon`, `beta`, `enterprise-only`) outside the selection vocabulary trips the detector because they erode the scan-at-a-glance property the closed vocabulary buys. Encode nuance in the cell's `detail` text, not in a new state. A blank cell is a content gap, not a styling choice. **Us-column singularity.** Exactly one column may carry `isUs: true` (zero is valid for a neutral comparison; two or more is positioning incoherence — "us" is a singular concept). The emphasis is a quiet `--us-band-bg` + foreground-derived border, never a brand-primary fill — a brand-coloured us-column opts out of the restraint that makes the comparison read as honest. diff --git a/hermes/design/visualize/templates/report/template.md b/hermes/design/visualize/templates/report/template.md index 2597462..2909909 100644 --- a/hermes/design/visualize/templates/report/template.md +++ b/hermes/design/visualize/templates/report/template.md @@ -1,17 +1,17 @@ --- name: Report -description: A structured long-form artifact for explaining findings, context, implications, and next steps. +description: A prose-led document explaining findings, evidence, implications, and next actions, with supporting tables or figures. --- # Report ## Use when -Use this template when the reader needs structured long-form artifact for explaining findings, context, implications, and next steps. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use when the main job is explaining findings and next steps, with prose, ordinary numeric tables, or supporting figures. Fits short decision briefs as well as longer reports. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +Use Comparison for a qualitative option-by-criterion matrix, Research brief for research-source synthesis or study documentation, and a plain answer when the material needs no document structure. ## Structure diff --git a/hermes/design/visualize/templates/research-brief/template.md b/hermes/design/visualize/templates/research-brief/template.md index 7b0c66d..a0f70b4 100644 --- a/hermes/design/visualize/templates/research-brief/template.md +++ b/hermes/design/visualize/templates/research-brief/template.md @@ -1,17 +1,17 @@ --- name: Research brief -description: A concise evidence synthesis for a research question, market, user, or competitor. +description: A research-source synthesis or study write-up, with source provenance and study-specific disclosures when applicable. --- # Research brief ## Use when -Use this template when the reader needs concise evidence synthesis for a research question, market, user, or competitor. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use to answer a research question from market, competitor, desk-research, or primary user-research sources. Interview studies use the methodology and citation contracts below; secondary-source or desk-research briefs still need source trails and claim-level provenance, but not interview-specific sections. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +Use Report for operational findings and next steps that need no research-source synthesis or study documentation. Use a plain answer when the question needs no structured evidence synthesis. ## Structure @@ -27,7 +27,7 @@ Read pattern recipes only when the content calls for them: `metadata` for docume Prior visual variants are no longer live authoring files. If the ask needs a distinct register or rendering route, express that choice in the artifact-local composition and document the reason in visible copy only when it helps the reader. -Default to `document` mode for source synthesis, market scans, competitor reads, user research summaries, and other prose-led evidence briefs. Interview studies use the methodology and citation contracts below; secondary-source or desk-research briefs still need source trails and claim-level provenance, but not interview-specific sections. Use canvas/dashboard primitives only when relationships or metrics are the main read and the source material supplies the model. +Default to `document` mode for source synthesis, market scans, competitor reads, user research summaries, and other prose-led evidence briefs. Use canvas/dashboard primitives only when relationships or metrics are the main read and the source material supplies the model. ## Hierarchy contract diff --git a/pi/agent/skills/visualize/SKILL.md b/pi/agent/skills/visualize/SKILL.md index 0be1122..34e30b0 100644 --- a/pi/agent/skills/visualize/SKILL.md +++ b/pi/agent/skills/visualize/SKILL.md @@ -26,20 +26,12 @@ allowed-tools: - Bash(bash */visualize/scripts/publish.sh*) - Bash(*/visualize/scripts/publish.sh*) description: > - Generate beautiful, on-brand HTML artifacts — reports, diagrams, diff - reviews, slide decks, plans, recaps, dashboards. Loads on creation - intents ("create a plan", "make me an implementation plan", - "generate a diagram", "build a slide deck", "draft a recap", - "visualize this", "render this as HTML", "make me a status update") - and exploration intents ("show me three layouts", "explore document - shapes", "compare visual treatments", "explore a new design system", - "compare replacement brand directions") and iteration intents ("make this beautiful", "polish this report", - "make this less generic", "design this", "theme this", "use my - brand", "iterate on this design", "review this artifact", "make - this bolder", "make this quieter", "simplify this design", - "animate this", "improve the look of", "give this a refresh"). - Captures brand from the user's codebase, asking, or live site, then - applies it to every artifact. + Create, explore, refine, and review on-brand HTML reports, diagrams, + diff reviews, slide decks, plans, recaps, and dashboards. Use to visualize + information, compare layouts or design systems, apply a brand or theme, + or improve an artifact's design, including simplifying, polishing, making + it bolder or quieter, and animating. Capture brand from code, conversation, + or a live site. --- # visualize — beautiful, on-brand HTML artifacts @@ -48,25 +40,21 @@ Generate self-contained HTML artifacts composed from `templates/*/template.md` c ## Design judgment -Identify what the reader needs to understand, make the important distinction visible, and retain the evidence and qualifications needed to interpret it correctly. +Identify the reader's task and make the important distinction visible, retaining the evidence and qualifications needed to interpret it. Before choosing a treatment, find the source's organizing relationship, contrast, sequence, decision, or object; let it shape the opening, section rhythm, and explanatory primitives. When none helps, prefer restrained reading over a manufactured organizing idea. -Find the artifact's organizing idea before choosing its visual treatment. Look for a relationship, contrast, sequence, decision, or object in the source that the composition itself can make easier to understand. Use that idea to shape the opening, section rhythm, and any explanatory primitive. When the source has no useful spatial or structural idea, prefer a restrained reading experience over manufacturing one. - -Artifact mode describes how the reader consumes the information, not the aesthetic family it must use. A document can use product-native, application-like, spatial, editorial, or technical-drawing grammar when that grammar serves the source, reader, and brand. Do not equate `document` with editorial publishing, or `canvas` with diagram chrome. - -Visual conviction can come from composition, typography, density, spatial rhythm, imagery, interaction, or color. Do not add hues, decoration, or components merely to make an artifact feel designed. A restrained palette can carry a strong point of view when another dimension does the expressive work. +Artifact mode describes consumption, not aesthetics: `document` need not mean editorial publishing, nor `canvas` diagram chrome. Composition, typography, density, spatial rhythm, imagery, interaction, or color can supply conviction. Do not add hues, decoration, or components merely to make the artifact feel designed. Before responding to feedback, compare the observation with the artifact's reader, purpose, source, and approved brief where one exists. Distinguish an implementation defect, a design that fails its existing requirements, and evidence that a requirement or assumption has changed. The current composition is a solution, not a constraint. Make authorized corrections within the existing brief directly. If feedback implies a change to established requirements that the user has not already approved, explain the proposed change and obtain agreement before editing. When several structural or visual directions remain plausible, recommend `explore artifact` within its supported scope. When the direction is established, use the ordinary creation or refinement workflow. Follow that workflow's approval requirements; a small correction does not need a new exploration. -Evaluate proposed fixes together against the reader's task. Do not turn every critique finding into an addition or treat a small diff as evidence that the direction is sound. Preserve decision-relevant deferred observations in existing review or task notes. +Judge proposed fixes together against the reader's task. Do not turn every critique finding into an addition or treat a small diff as evidence of a sound direction. Retain decision-relevant deferred observations in existing review or task notes. ## Commands -`/visualize` invokes the skill. The argument tells the agent what to do. +`/visualize` takes a command or topic/path. -**Default (no command, or the first argument is a topic):** `/visualize ` creates a new artifact. The agent picks a template from intent across all of `templates/`, composes against the resolved project or artifact-theme context, writes self-contained HTML. **The flow is gated:** preflight checklist + shape-gate before code, no self-authored briefs. See `reference/create.md`. +**Default (topic/path without a command):** create self-contained HTML using a template and resolved context. Read `reference/create.md`; preflight and user-approved shape precede code. An agent-authored brief cannot approve itself. **Named commands:** @@ -82,12 +70,12 @@ Evaluate proposed fixes together against the reader's task. Do not turn every cr | **Evaluate** | `review` | `` | Deterministic detector findings + LLM judgment. Reports; doesn't modify the file. | `reference/review.md` | | **Publish** | `publish` | `` | Push the artifact to display.dev via MCP / CLI / HTTP cascade. | `reference/publish.md` | -Invocation forms: `/visualize teach`, `/visualize explore artifact ./report.html`, `/visualize polish ./report.html`, `/visualize publish ./diagram.html`. On hosts without a slash-command form, the skill loads on intent-match from the description above; natural-language is the primary entry there. +Example: `/visualize polish ./report.html`. On hosts without slash commands, natural-language intent is the primary entry. ## Routing rules 1. **No argument**: render the Commands table above as the user-facing menu, grouped by category. Ask what they'd like to do. -2. **First word matches a command**: **load its reference file before doing anything else.** Non-negotiable — the table row + this section is insufficient; the procedure lives in the reference. Everything after the command name is the target. +2. **First word matches a command**: **load its reference before acting**; the table is not the procedure. Everything after the command name is the target. 3. **Natural-language intent**: requests to compare design alternatives load `reference/explore.md`; capturing or reconciling project identity loads `reference/teach.md`. Otherwise load `reference/create.md` for creation or an explicitly requested restyling of an existing artifact. A named theme follows Artifact themes below; it does not require an exploration round. 4. **Relationship-diagram route during creation**: when preflight first identifies a likely relationship diagram, load `reference/diagram.md` and the one tentative non-spatial type reference needed for that figure before presenting the shape gate. For multi-figure artifacts, load one reference for each distinct tentative family: `reference/diagram-flow.md`, `reference/diagram-system.md`, `reference/diagram-sequence.md`, `reference/diagram-state.md`, or `reference/diagram-hierarchy.md`. Spatial figures use `reference/diagram.md` alone. If approval changes a figure's type, load the replacement reference before authoring; do not load unrelated families. 5. **Generated-image route during creation**: when the approved shape requires generated bitmap imagery, load `reference/image-generation.md` before selecting or invoking a route. Use only the active callable inventory or an explicitly selected API adapter. Never infer a route from a key, executable, mount, or model claim, and never retry or fall back after an ambiguous attempt. @@ -95,25 +83,18 @@ Invocation forms: `/visualize teach`, `/visualize explore artifact ./report.html ## Hand-off output shape -After a refine verb (`simplify` / `bolder` / `quieter` / `animate`) finishes its run, summarise to the user in plain markdown. Don't render the summary as a fenced code block — it's conversational output, not machine-readable. Vary phrasing across runs; pick wording per context (engineer reading detector output vs. designer iterating on a brand brief). `polish` has its own output shape — see `reference/polish.md`. - -Every refine run's summary covers four facts: - -- Which verb ran, against which artifact. -- What the verb actually did. Pull the verb-specific content from the per-verb reference's "what to surface" list (focal moment, cuts + audit trail, strategy, what stayed, hero moment, reduced-motion handling — depends on the verb). -- Diff size as a percent of the artifact. -- Which next action makes sense, if any. Polish is the default next step from a successful refine run. - -Variant rules (behaviour, not surface text): +After `simplify` / `bolder` / `quieter` / `animate`, report in conversational markdown: verb and target, changes drawn from the reference's "what to surface" list, diff percentage, and the appropriate next action. Successful refinement defaults to `polish`, which has its own output shape in `reference/polish.md`. -- **Context source note.** If the run cannot use a persisted `DESIGN.md` / `PRODUCT.md`, mention once which fallback source anchored the work: project instructions, README/docs, generated seed, or Clean defaults. Also nudge the user to run `/visualize teach` so that fallback can become a real brand profile. Clean defaults are the last resort after the Brand profile rules below find no usable project guidance. -- **Diff exceeded the 40% guard.** Stop refinement and report the affected scope. Apply Design judgment to recommend exploration when the structural direction remains unresolved, or a fresh creation pass when it is established. Do not continue into polish. -- **Verb shouldn't have run** (Absolute bans present, no decoration to remove, no focal moment, etc.). Skip the standard run summary entirely. Surface a short refusal that names the reason and routes to the right alternative verb. Each per-verb reference's "When `` is the right verb (and when it isn't)" section enumerates the verb's specific refusal conditions. +Variant rules: -Tone is conversational. Lead with what changed, not with a banner. Don't capitalise words for emphasis. Don't print a ` pass complete ·` header — the summary's content is the proof of completion. +- **Fallback context:** name the source once (project instructions, README/docs, seed, or Clean) and nudge `/visualize teach`. Follow Brand profile's fallback hierarchy. +- **Diff >40%:** stop, report the scope, and apply Design judgment to recommend exploration if direction is unresolved or fresh creation if established. Do not continue to polish. +- **Verb shouldn't have run:** use the reference's refusal conditions; replace the standard summary with a short reason and the appropriate alternative. For `animate` specifically: when the brand declares `motion: none`, a fifth variant applies — see `reference/animate.md`. +Lead with changes, vary phrasing for the reader, and avoid fenced summaries, capitalized emphasis, or ` pass complete ·` banners. + ## Absolute bans Match-and-refuse. Apply on every command and the default creation flow. These ban specific patterns — not aesthetics, not registers. A brand can declare a font, a hue, or a layout that looks unusual; it cannot redeem any of these patterns by declaring them as identity. An explicit `.visualize-detect.json` skip can waive only a detector-backed ban with a concrete rule ID; it is project policy, not runtime brand suppression, and cannot waive a Layer-2 ban. @@ -191,21 +172,30 @@ These are not brand aesthetics; they are observed model reflexes with required c ## AI slop test (two altitudes) -Run both. The second catches what the first misses. +Run both tests: -**First-order**: if someone could guess the template + palette from the topic alone, you've hit the first training-data reflex. Topic stereotypes are prompts to inspect the brief, not color prohibitions: red, purple gradients, or navy-and-gold can fit a specific artifact. Rework unsupported defaults, not approved identity. +- **First-order:** could the topic alone predict the template and palette? Inspect unsupported stereotypes, not approved identity; hue names are not prohibitions. +- **Second-order:** could topic plus anti-references predict the aesthetic family? Avoid substituting another saturated reflex, such as cream/Georgia/margin-note editorial, mono/grid/heavy-border terminal, or uppercase/grotesk/grid Swiss-poster when the source and register do not support it. -**Second-order**: if someone could guess the aesthetic family from topic-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic," "fintech that's not navy-and-gold → terminal-native dark mode"), the second-tier reflex isn't avoided. Currently-saturated families to watch for: editorial-Tufte clone (cream + Georgia + side-margin notes when the topic isn't editorial), brutalist-terminal clone (mono + grid + heavy borders when the topic isn't dev-tool), Swiss-poster clone (uppercase + grotesk + grid when the topic isn't presentation). Rework until both altitudes return "no, you couldn't have guessed." +Rework unsupported defaults until neither test predicts the treatment; preserve approved identity. ## Brand profile -Every render reads available `DESIGN.md` (visual identity + design tokens) and `PRODUCT.md` (voice, audience, tone) at the project root. `teach` derives custom design tokens for the brand and writes them in `DESIGN.md` as YAML frontmatter (the Google Stitch canonical format: machine-readable tokens) plus a six-section markdown body (Overview / Colors / Typography / Elevation / Components / Do's and Don'ts), with a sidecar `tokens.css` at the project root carrying the CSS-form tokens templates read at render time. Project profiles retain concrete tokens, not a `theme: ` pointer. +Every render reads available project-root `DESIGN.md` (visual identity/tokens), `PRODUCT.md` (voice/audience/tone), and `tokens.css`. `teach` writes concrete project tokens in Stitch-format `DESIGN.md` plus the CSS sidecar, not a `theme: ` pointer; its schema and derivation procedure live in `reference/teach.md`. + +**Authority:** persisted `DESIGN.md` and `tokens.css` own visual tokens; `PRODUCT.md` owns voice and audience. Project instructions fill gaps without overriding persisted tokens unless the user explicitly says otherwise in the current request. Apply Artifact themes' approved exceptions before locking context. Brand authority is identity-scoped. If the request fixes a named identity but the resolved project profile clearly belongs to another product, do not substitute, relabel, or approximate it. Stop before the shape gate or any artifact edit and request matching authority or explicit permission for an artifact-only override. -The design systems under `design-systems/` are reference packages with design guidance, tokens, and previews. `teach` and System Explore read them when deriving project identities; artifact creation and exploration can use them as themes under the shared contract below. +`design-systems/` packages supply guidance, tokens, and previews for `teach`, System Explore, and artifact themes. + +**Fallback when no DESIGN.md exists:** + +1. Preserve an approved artifact reference as the baseline where project guidance is absent; do not replace it with a seed or Clean. +2. Otherwise read available project instructions (`AGENTS.md`, `CLAUDE.md`, README, docs) for positioning, visual direction, anti-references, and design principles. Treat usable guidance as binding brand context, including named fonts, palette roles, logo/mark rules, density/register, and anti-references, not optional mood. Follow referenced tokens, stylesheets, logo components, and guidelines before approximating from prose. Named fonts and palette roles override Clean's values; anti-references rule out the corresponding fallback register. Clean supplies the semantic token surface, not its fonts, monochrome palette, or warm/cream defaults. +3. Only with no usable visual direction, run `node $SKILL_DIR/scripts/palette.mjs --from ""`. Compose temporary primary, background, foreground, accent, chart, and state tokens from the seed and brief, using its `derived` contrast numbers, chroma budgets, and light/dark ladders. Do not estimate those values or copy Clean unchanged. If the seed fights the brief, re-run with `--not ` or `--vary ` and note the veto in the shape gate. Validate composed tokens with `node $SKILL_DIR/scripts/palette.mjs --check --strict`; fix errors (exit 2) before render. -**Fallback when no DESIGN.md exists:** an approved artifact reference supplies the visual baseline where project guidance is absent; do not replace it with a seed or Clean defaults. Otherwise, first read available project instructions (`AGENTS.md`, `CLAUDE.md`, README, docs) for product positioning, visual direction, anti-references, and design principles. If those files contain usable brand/design guidance, treat it as binding brand context while using Clean's token **surface** as the structural floor. Explicit cues in repo guidance override Clean values: named fonts become the artifact font stack, named palette roles become the artifact color tokens, and named anti-references rule out the corresponding fallback register. If the guidance points at concrete token files, stylesheet files, logo components, or design guidelines, read those referenced files and use their values before approximating from prose. Using Clean's token surface means keeping the semantic variable shape, not copying Clean's fonts, monochrome values, or warm/cream defaults. Only run `node $SKILL_DIR/scripts/palette.mjs --from ""` when the project has no usable visual direction at all. When a seed is used, compose the temporary `--primary`, `--background`, `--foreground`, `--accent`, chart, and state tokens from the seed + artifact brief; do not copy Clean's monochrome palette unchanged. Use the script's `derived` block (real contrast numbers, per-hue chroma budgets, light + dark lightness ladders) instead of estimating those values; if the seed's register fights the brief, re-run with `--not ` or `--vary ` and note the veto in the shape gate. After composing, validate with `node $SKILL_DIR/scripts/palette.mjs --check --strict` and fix error findings (exit 2) before render. Nudge `/visualize teach` once per session so repo guidance or the temporary seed can become a real brand profile. +Nudge `/visualize teach` once per session when using fallback context. **Refine verbs on missing persisted brand files:** `simplify` / `bolder` / `quieter` / `animate` / `polish` use the same fallback hierarchy as creation. Project instructions, README/docs, or other already-loaded context can be a valid qualitative brand anchor. Clean defaults are only the anchor when no usable project guidance exists. Whenever a fallback source is used, mention that source once and nudge `/visualize teach` so the fallback can become a real brand profile. @@ -213,15 +203,15 @@ The design systems under `design-systems/` are reference packages with design gu ## Artifact themes -A theme is a reference design system applied to one artifact, not a new stored object or a project-wide adoption. Use the current project system by default. Resolve binding project choices, approved artifact exceptions, and open design dimensions before borrowing from a reference. A named reference or a request to make an artifact more expressive does not silently override binding project choices; clarify conflicts that the request leaves unresolved. Explicit permission to replace visual styling applies only to the named artifact and dimensions. Do not invent constraints where the project is silent. +A theme is a reference design system applied to one artifact, not a new stored object or a project-wide adoption. Default to the project system; resolve binding choices, approved exceptions, and open dimensions before borrowing. A named reference or request for more expression does not silently override binding choices. Clarify unresolved conflicts; explicit replacement permission covers only the named artifact and dimensions. Do not invent constraints where the project is silent. -Read the selected `design-systems//README.md` when present, then its `DESIGN.md` and `tokens.css`. README is the package entry point; DESIGN owns suitability, identity, and adaptation guidance. Use previews to understand the treatment, not as required layouts. If the user wants alternatives, propose a small relevant shortlist rather than loading the entire catalog. A missing README does not make a package unavailable. +Read the selected package's `README.md` when present, then `DESIGN.md` and `tokens.css`. DESIGN owns suitability, identity, and adaptation. Previews illustrate treatment, not required layouts. When the user wants alternatives, offer a small relevant shortlist; do not load the whole catalog. A missing README does not make a package unavailable. -Apply a named treatment through ordinary creation or revision; compare unresolved treatments through `explore artifact`. Neither requires a new layout or a project profile first. For new content, derive structure from the reader's task and source. For existing artifacts, preserve content, order, assets, and behavior unless those changes were requested. A broad restyling uses `reference/create.md` with that preservation scope, not a narrow refine verb forced past its diff guard. Existing approval gates still apply; an explicit request already covering the proposed changes does not need reconfirmation. +Apply a treatment through creation or revision; compare unresolved treatments through `explore artifact`. Neither requires a new layout or project profile. Derive new structure from source and reader task. Preserve existing content, order, assets, and behavior unless changes were requested. Broad restyling uses `reference/create.md` with that scope rather than exceeding a refine verb's diff guard. Existing approval gates apply; an explicit request covering the proposed changes needs no reconfirmation. -Translate the reference's hierarchy, spacing, surfaces, and component treatment as well as its palette and type. Keep non-overridden project choices. Embed the resolved tokens, including designed light/dark and OS-dark behavior, in the artifact; do not replace the project's token source. Verify against the resolved artifact context, not the overridden project values. Describe partial borrowing and retained constraints rather than claiming an unchanged reference application. Keep the approved exception and its scope in existing task notes or a short artifact comment so later refinement can preserve it; unexplained styling drift alone is not approval. +Translate hierarchy, spacing, surfaces, and component treatment alongside palette and type. Preserve non-overridden project choices. Embed resolved tokens with light, explicit-dark, and OS-dark behavior in the artifact; do not replace the project's token source. Verify against the resolved artifact context, not overridden values. Describe partial borrowing and retained constraints accurately. Record approved exceptions and scope in existing task notes or a short artifact comment for later refinement; unexplained drift is not approval. -For project-wide capture or direct derivation, use `teach`. To compare new or explicitly requested replacement systems, use `explore system`. Neither route is a prerequisite for artifact themes. +Project-wide capture or derivation uses `teach`; comparing new or explicitly requested replacement systems uses `explore system`. Neither is a prerequisite for artifact themes. ## Universal laws diff --git a/pi/agent/skills/visualize/reference/create.md b/pi/agent/skills/visualize/reference/create.md index b163aa4..b8d194b 100644 --- a/pi/agent/skills/visualize/reference/create.md +++ b/pi/agent/skills/visualize/reference/create.md @@ -10,7 +10,7 @@ Autonomous harnesses (Codex-class) have been observed jumping to file writes bef Before composing, confirm: -1. **Context loaded.** Resolve artifact context, brand/context source, token source, and fallback behavior per SKILL.md before choosing a template or writing code. If fallback context is used because `DESIGN.md` / `PRODUCT.md` are absent, extract binding brand cues from project instructions: named fonts, palette roles, logo/mark rules, density/register, and anti-references. If those instructions cite token files, stylesheets, design guidelines, or logo components, read those files before composing. Do not treat those cues as optional mood. **Brand-source precedence when sources disagree:** persisted `DESIGN.md` and `tokens.css` win for visual tokens (colors, fonts, surfaces); `PRODUCT.md` wins for voice and audience; fallback project instructions fill gaps but do not override persisted brand tokens unless the user explicitly says so in the current request. Apply SKILL.md's Artifact themes contract before locking the visual context; approved artifact exceptions participate in that resolution. +1. **Context loaded.** Resolve context and tokens using SKILL.md's Brand profile and Artifact themes contracts, including fallback sources, their referenced assets, and approved exceptions, before choosing a template or writing code. 2. **Brand-fidelity lock.** From the artifact context resolved in step 1, record the applicable invariants across the categories below. These are enforceable, not aspirational. Do not invent invariants where the brand profile is silent — absence is a valid answer for any individual category. - **Named fonts.** If the brand profile or fallback source names specific fonts, those fonts must lead the body / heading / code CSS stacks in the artifact. `system-ui`, `Inter`, `-apple-system`, or any other generic sans cannot lead the stack unless the brand explicitly names them. - **Named palette / color system.** If the brand profile names palette roles or uses a specific color system (OKLCH, `color-mix`, `lab`, `lch`), `--background` / `--foreground` / `--primary` / borders / surfaces must derive from that palette and use that color system, not from fallback cream-paper, generic grays, or seed-generated hues. @@ -25,7 +25,7 @@ Before composing, confirm: - `deck` — slide or presentation sequence where each screen is consumed separately. Mode describes consumption, not aesthetic register. A `document` can still use product-native, application-like, spatial, editorial, or technical-drawing grammar when that grammar expresses the source and brand. Do not let the conservative mode default choose the artifact's look for you. -5. **Template picked.** Select from `templates/*/template.md` using template name, description, Use when, and Do not use when. Templates are starting points, not fixed artifact shells: customize the chosen template to fit the reader job and source, then fall back to pattern recipes for recurring structures the template does not cover. Template names are weak evidence; required structure and reader job are strong evidence. Pick the most specific template only when its required structure fits the source without inventing missing fields. If a named template would force a time axis, live-status semantics, escalation path, operational checks, slide sequence, scoring model, or other content the source does not provide, choose the broader document template and borrow only bounded primitives. Bounded primitives are small structures inside the chosen mode — e.g. labeled time-window rows, status marks, compact scenario tables, one contained topology figure — not the named template's full chrome or layout system. State the choice with one-line rationale. +5. **Template picked.** Start candidate selection from the name, description, Use when, and Do not use when sections of `templates/*/template.md`. Read further candidate sections only when needed to resolve uncertainty about structural fit. Templates are starting points, not fixed artifact shells: customize the chosen template to fit the reader job and source, then fall back to pattern recipes for recurring structures the template does not cover. Template names are weak evidence; required structure and reader job are strong evidence. Pick the most specific template only when its required structure fits the source without inventing missing fields. If a named template would force a time axis, live-status semantics, escalation path, operational checks, slide sequence, scoring model, or other content the source does not provide, choose the broader document template and borrow only bounded primitives. Bounded primitives are small structures inside the chosen mode — e.g. labeled time-window rows, status marks, compact scenario tables, one contained topology figure — not the named template's full chrome or layout system. State the choice with one-line rationale. 6. **Composition reflex check.** Before sketching shape, name up to three artifact-class defaults you must NOT assume — at least one when an obvious reflex exists for the class. The defaults are moves that appear across every AI-generated version of this artifact class regardless of source or brand — the median answer to the class's prompt. The reflex defaults for any artifact class tend to cluster around the dominant masthead pattern, the default section rhythm, the default verdict/answer placement, and the default secondary-navigation device (TOC, sidebar, sticky chrome). Identify the ones that apply to the class at hand (up to three). diff --git a/pi/agent/skills/visualize/reference/polish.md b/pi/agent/skills/visualize/reference/polish.md index 2b17d2c..ce80dea 100644 --- a/pi/agent/skills/visualize/reference/polish.md +++ b/pi/agent/skills/visualize/reference/polish.md @@ -11,7 +11,7 @@ Walk every applicable quality dimension and report findings against the reader's Read in order: 1. **The artifact.** Open the file, scroll it end-to-end in your head. Notice what the eye lands on first, what feels off, what reads as "agent eyeballed it." -2. **The detector.** Run `node $SKILL_DIR/scripts/detect.mjs --json ` for the mechanical floor. Detector output is **defect-evidence**, never **done-evidence** — a clean result is not proof the artifact is strong. The detector catches what regex can identify; polish covers everything else. +2. **The detector.** Run `node $SKILL_DIR/scripts/detect.mjs --json ` for the mechanical floor; apply SKILL.md's Universal law 7 when interpreting the result. ## Discovery: name the root cause, not just the symptom @@ -170,7 +170,7 @@ Skipped verification accumulates as "polish reports clean but the artifact is br If the artifact needs broad rework, polish has misfired. The escape: -- **Artifact carries ≥3 Absolute bans** → refuse and route to `/visualize simplify` first. Simplify's job is removing ban patterns; polish assumes a clean baseline. (SKILL.md's "Refine verbs on artifacts that carry ≥3 Absolute bans" rule applies.) +- **Ban-heavy artifact** → apply SKILL.md's "Refine verbs on artifacts that carry ≥3 Absolute bans" refusal and routing contract. - **Artifact needs broad rework beyond polish** → stop refinement and apply SKILL.md's Hand-off output shape and Design judgment to recommend the next action. - **Do not hand off to another Refine verb expecting it to come back.** The Refine verbs (`simplify` / `bolder` / `quieter` / `animate`) hand off to polish, but polish doesn't hand off to them — that creates a cycle. When polish refuses, recommend the next action to the user; do not start another command. diff --git a/pi/agent/skills/visualize/reference/review.md b/pi/agent/skills/visualize/reference/review.md index cdc3f78..6ba6c9e 100644 --- a/pi/agent/skills/visualize/reference/review.md +++ b/pi/agent/skills/visualize/reference/review.md @@ -92,8 +92,7 @@ Things detect.mjs deliberately doesn't try to catch: register-dependence, vocab- - **Mock identity** beyond the obvious: fictitious customer quotes ("Sarah Johnson, VP Marketing"), placeholder phone / address / company / brand names that aren't in the obvious set (Acme, Globex, Anytown, TBD, XXX-XXX-XXXX). - **Slop openers**: "leverage / streamline / empower / unlock / elevate / unleash / robust / holistic / seamless / cutting-edge / next-gen / In conclusion / TL;DR:" packed into the opening paragraphs. -- **Sycophant footers**: "I hope you find this useful", "Happy to clarify", "Hopefully this addresses your needs", "Best, Claude", anything signed by an AI. -- **Imperative tricolon** ("Ship faster. Build smarter. Scale forever."): three commands ending in periods, regardless of content. Can't be redeemed. +- **Sycophant footers and imperative tricolons**: inspect against SKILL.md BAN 7 and BAN 6. **Brand- and register-dependent slop** (mechanical detector would false-positive). These judgment calls exclude SKILL.md's Absolute bans, which resolved context cannot redeem. When deciding the remaining calls, consult [color.md](color.md) / [typography.md](typography.md) / [spatial.md](spatial.md) / [copy.md](copy.md) for the deeper material: @@ -161,7 +160,7 @@ Context-suppressed detector results are audit evidence rather than actionable fi - **≥4 `slop/center-everything` declarations in a non-Bauhaus / non-academic register = pattern.** Single centered hero is fine. When unsure, default to surfacing it as info + naming the aggregate count. -- **Universal law 6**: the reader is the judge. Does each finding make the reader's job harder, or just satisfy a rule? +- Apply SKILL.md's Universal law 6 to every finding. ## Output format (mandatory shape) diff --git a/pi/agent/skills/visualize/templates/comparison/template.md b/pi/agent/skills/visualize/templates/comparison/template.md index 8ca488c..5afa071 100644 --- a/pi/agent/skills/visualize/templates/comparison/template.md +++ b/pi/agent/skills/visualize/templates/comparison/template.md @@ -1,17 +1,17 @@ --- name: Comparison -description: A decision-support artifact for comparing options, tradeoffs, and recommendations. +description: A qualitative options matrix with yes/no/partial/varies cell states, supporting values, and tradeoffs. --- # Comparison ## Use when -Use this template when the reader needs decision-support artifact for comparing options, tradeoffs, and recommendations. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use for one option-by-criterion matrix. Every cell carries both a state (`yes` / `no` / `partial` / `varies`) and a supporting value; explanations carry nuance. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +For numeric observations without an option-by-criterion evaluation, use Report with an ordinary table. Split multiple comparison matrices into separate artifacts or use Report with embedded comparison figures. ## Structure @@ -37,9 +37,9 @@ The first two phone screens must deliver title, thesis, and essential context wi ## Failure modes -**Single-table rule.** Exactly one `
` per artifact. A second `cmp-table` block trips the detector — multi-table comparisons fragment the read; split them into multiple Comparison artifacts or fold into a Report with embedded comparison figures. +**Single-table rule.** Render the matrix as `
`. A second `cmp-table` block trips the detector because multi-table comparisons fragment the read. -**Cell-state vocabulary is closed.** States are drawn from `yes` / `no` / `partial` / `varies` — full stop. Inventing new states (`coming-soon`, `beta`, `enterprise-only`) trips the detector because they erode the scan-at-a-glance property the closed vocabulary buys. Encode nuance in the cell's `detail` text, not in a new state. Every cell carries both a `state` and a `value`; a blank cell is a content gap, not a styling choice. +**Invalid cell states.** Inventing states (`coming-soon`, `beta`, `enterprise-only`) outside the selection vocabulary trips the detector because they erode the scan-at-a-glance property the closed vocabulary buys. Encode nuance in the cell's `detail` text, not in a new state. A blank cell is a content gap, not a styling choice. **Us-column singularity.** Exactly one column may carry `isUs: true` (zero is valid for a neutral comparison; two or more is positioning incoherence — "us" is a singular concept). The emphasis is a quiet `--us-band-bg` + foreground-derived border, never a brand-primary fill — a brand-coloured us-column opts out of the restraint that makes the comparison read as honest. diff --git a/pi/agent/skills/visualize/templates/report/template.md b/pi/agent/skills/visualize/templates/report/template.md index 2597462..2909909 100644 --- a/pi/agent/skills/visualize/templates/report/template.md +++ b/pi/agent/skills/visualize/templates/report/template.md @@ -1,17 +1,17 @@ --- name: Report -description: A structured long-form artifact for explaining findings, context, implications, and next steps. +description: A prose-led document explaining findings, evidence, implications, and next actions, with supporting tables or figures. --- # Report ## Use when -Use this template when the reader needs structured long-form artifact for explaining findings, context, implications, and next steps. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use when the main job is explaining findings and next steps, with prose, ordinary numeric tables, or supporting figures. Fits short decision briefs as well as longer reports. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +Use Comparison for a qualitative option-by-criterion matrix, Research brief for research-source synthesis or study documentation, and a plain answer when the material needs no document structure. ## Structure diff --git a/pi/agent/skills/visualize/templates/research-brief/template.md b/pi/agent/skills/visualize/templates/research-brief/template.md index 7b0c66d..a0f70b4 100644 --- a/pi/agent/skills/visualize/templates/research-brief/template.md +++ b/pi/agent/skills/visualize/templates/research-brief/template.md @@ -1,17 +1,17 @@ --- name: Research brief -description: A concise evidence synthesis for a research question, market, user, or competitor. +description: A research-source synthesis or study write-up, with source provenance and study-specific disclosures when applicable. --- # Research brief ## Use when -Use this template when the reader needs concise evidence synthesis for a research question, market, user, or competitor. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use to answer a research question from market, competitor, desk-research, or primary user-research sources. Interview studies use the methodology and citation contracts below; secondary-source or desk-research briefs still need source trails and claim-level provenance, but not interview-specific sections. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +Use Report for operational findings and next steps that need no research-source synthesis or study documentation. Use a plain answer when the question needs no structured evidence synthesis. ## Structure @@ -27,7 +27,7 @@ Read pattern recipes only when the content calls for them: `metadata` for docume Prior visual variants are no longer live authoring files. If the ask needs a distinct register or rendering route, express that choice in the artifact-local composition and document the reason in visible copy only when it helps the reader. -Default to `document` mode for source synthesis, market scans, competitor reads, user research summaries, and other prose-led evidence briefs. Interview studies use the methodology and citation contracts below; secondary-source or desk-research briefs still need source trails and claim-level provenance, but not interview-specific sections. Use canvas/dashboard primitives only when relationships or metrics are the main read and the source material supplies the model. +Default to `document` mode for source synthesis, market scans, competitor reads, user research summaries, and other prose-led evidence briefs. Use canvas/dashboard primitives only when relationships or metrics are the main read and the source material supplies the model. ## Hierarchy contract diff --git a/skills/visualize/SKILL.md b/skills/visualize/SKILL.md index 0be1122..34e30b0 100644 --- a/skills/visualize/SKILL.md +++ b/skills/visualize/SKILL.md @@ -26,20 +26,12 @@ allowed-tools: - Bash(bash */visualize/scripts/publish.sh*) - Bash(*/visualize/scripts/publish.sh*) description: > - Generate beautiful, on-brand HTML artifacts — reports, diagrams, diff - reviews, slide decks, plans, recaps, dashboards. Loads on creation - intents ("create a plan", "make me an implementation plan", - "generate a diagram", "build a slide deck", "draft a recap", - "visualize this", "render this as HTML", "make me a status update") - and exploration intents ("show me three layouts", "explore document - shapes", "compare visual treatments", "explore a new design system", - "compare replacement brand directions") and iteration intents ("make this beautiful", "polish this report", - "make this less generic", "design this", "theme this", "use my - brand", "iterate on this design", "review this artifact", "make - this bolder", "make this quieter", "simplify this design", - "animate this", "improve the look of", "give this a refresh"). - Captures brand from the user's codebase, asking, or live site, then - applies it to every artifact. + Create, explore, refine, and review on-brand HTML reports, diagrams, + diff reviews, slide decks, plans, recaps, and dashboards. Use to visualize + information, compare layouts or design systems, apply a brand or theme, + or improve an artifact's design, including simplifying, polishing, making + it bolder or quieter, and animating. Capture brand from code, conversation, + or a live site. --- # visualize — beautiful, on-brand HTML artifacts @@ -48,25 +40,21 @@ Generate self-contained HTML artifacts composed from `templates/*/template.md` c ## Design judgment -Identify what the reader needs to understand, make the important distinction visible, and retain the evidence and qualifications needed to interpret it correctly. +Identify the reader's task and make the important distinction visible, retaining the evidence and qualifications needed to interpret it. Before choosing a treatment, find the source's organizing relationship, contrast, sequence, decision, or object; let it shape the opening, section rhythm, and explanatory primitives. When none helps, prefer restrained reading over a manufactured organizing idea. -Find the artifact's organizing idea before choosing its visual treatment. Look for a relationship, contrast, sequence, decision, or object in the source that the composition itself can make easier to understand. Use that idea to shape the opening, section rhythm, and any explanatory primitive. When the source has no useful spatial or structural idea, prefer a restrained reading experience over manufacturing one. - -Artifact mode describes how the reader consumes the information, not the aesthetic family it must use. A document can use product-native, application-like, spatial, editorial, or technical-drawing grammar when that grammar serves the source, reader, and brand. Do not equate `document` with editorial publishing, or `canvas` with diagram chrome. - -Visual conviction can come from composition, typography, density, spatial rhythm, imagery, interaction, or color. Do not add hues, decoration, or components merely to make an artifact feel designed. A restrained palette can carry a strong point of view when another dimension does the expressive work. +Artifact mode describes consumption, not aesthetics: `document` need not mean editorial publishing, nor `canvas` diagram chrome. Composition, typography, density, spatial rhythm, imagery, interaction, or color can supply conviction. Do not add hues, decoration, or components merely to make the artifact feel designed. Before responding to feedback, compare the observation with the artifact's reader, purpose, source, and approved brief where one exists. Distinguish an implementation defect, a design that fails its existing requirements, and evidence that a requirement or assumption has changed. The current composition is a solution, not a constraint. Make authorized corrections within the existing brief directly. If feedback implies a change to established requirements that the user has not already approved, explain the proposed change and obtain agreement before editing. When several structural or visual directions remain plausible, recommend `explore artifact` within its supported scope. When the direction is established, use the ordinary creation or refinement workflow. Follow that workflow's approval requirements; a small correction does not need a new exploration. -Evaluate proposed fixes together against the reader's task. Do not turn every critique finding into an addition or treat a small diff as evidence that the direction is sound. Preserve decision-relevant deferred observations in existing review or task notes. +Judge proposed fixes together against the reader's task. Do not turn every critique finding into an addition or treat a small diff as evidence of a sound direction. Retain decision-relevant deferred observations in existing review or task notes. ## Commands -`/visualize` invokes the skill. The argument tells the agent what to do. +`/visualize` takes a command or topic/path. -**Default (no command, or the first argument is a topic):** `/visualize ` creates a new artifact. The agent picks a template from intent across all of `templates/`, composes against the resolved project or artifact-theme context, writes self-contained HTML. **The flow is gated:** preflight checklist + shape-gate before code, no self-authored briefs. See `reference/create.md`. +**Default (topic/path without a command):** create self-contained HTML using a template and resolved context. Read `reference/create.md`; preflight and user-approved shape precede code. An agent-authored brief cannot approve itself. **Named commands:** @@ -82,12 +70,12 @@ Evaluate proposed fixes together against the reader's task. Do not turn every cr | **Evaluate** | `review` | `` | Deterministic detector findings + LLM judgment. Reports; doesn't modify the file. | `reference/review.md` | | **Publish** | `publish` | `` | Push the artifact to display.dev via MCP / CLI / HTTP cascade. | `reference/publish.md` | -Invocation forms: `/visualize teach`, `/visualize explore artifact ./report.html`, `/visualize polish ./report.html`, `/visualize publish ./diagram.html`. On hosts without a slash-command form, the skill loads on intent-match from the description above; natural-language is the primary entry there. +Example: `/visualize polish ./report.html`. On hosts without slash commands, natural-language intent is the primary entry. ## Routing rules 1. **No argument**: render the Commands table above as the user-facing menu, grouped by category. Ask what they'd like to do. -2. **First word matches a command**: **load its reference file before doing anything else.** Non-negotiable — the table row + this section is insufficient; the procedure lives in the reference. Everything after the command name is the target. +2. **First word matches a command**: **load its reference before acting**; the table is not the procedure. Everything after the command name is the target. 3. **Natural-language intent**: requests to compare design alternatives load `reference/explore.md`; capturing or reconciling project identity loads `reference/teach.md`. Otherwise load `reference/create.md` for creation or an explicitly requested restyling of an existing artifact. A named theme follows Artifact themes below; it does not require an exploration round. 4. **Relationship-diagram route during creation**: when preflight first identifies a likely relationship diagram, load `reference/diagram.md` and the one tentative non-spatial type reference needed for that figure before presenting the shape gate. For multi-figure artifacts, load one reference for each distinct tentative family: `reference/diagram-flow.md`, `reference/diagram-system.md`, `reference/diagram-sequence.md`, `reference/diagram-state.md`, or `reference/diagram-hierarchy.md`. Spatial figures use `reference/diagram.md` alone. If approval changes a figure's type, load the replacement reference before authoring; do not load unrelated families. 5. **Generated-image route during creation**: when the approved shape requires generated bitmap imagery, load `reference/image-generation.md` before selecting or invoking a route. Use only the active callable inventory or an explicitly selected API adapter. Never infer a route from a key, executable, mount, or model claim, and never retry or fall back after an ambiguous attempt. @@ -95,25 +83,18 @@ Invocation forms: `/visualize teach`, `/visualize explore artifact ./report.html ## Hand-off output shape -After a refine verb (`simplify` / `bolder` / `quieter` / `animate`) finishes its run, summarise to the user in plain markdown. Don't render the summary as a fenced code block — it's conversational output, not machine-readable. Vary phrasing across runs; pick wording per context (engineer reading detector output vs. designer iterating on a brand brief). `polish` has its own output shape — see `reference/polish.md`. - -Every refine run's summary covers four facts: - -- Which verb ran, against which artifact. -- What the verb actually did. Pull the verb-specific content from the per-verb reference's "what to surface" list (focal moment, cuts + audit trail, strategy, what stayed, hero moment, reduced-motion handling — depends on the verb). -- Diff size as a percent of the artifact. -- Which next action makes sense, if any. Polish is the default next step from a successful refine run. - -Variant rules (behaviour, not surface text): +After `simplify` / `bolder` / `quieter` / `animate`, report in conversational markdown: verb and target, changes drawn from the reference's "what to surface" list, diff percentage, and the appropriate next action. Successful refinement defaults to `polish`, which has its own output shape in `reference/polish.md`. -- **Context source note.** If the run cannot use a persisted `DESIGN.md` / `PRODUCT.md`, mention once which fallback source anchored the work: project instructions, README/docs, generated seed, or Clean defaults. Also nudge the user to run `/visualize teach` so that fallback can become a real brand profile. Clean defaults are the last resort after the Brand profile rules below find no usable project guidance. -- **Diff exceeded the 40% guard.** Stop refinement and report the affected scope. Apply Design judgment to recommend exploration when the structural direction remains unresolved, or a fresh creation pass when it is established. Do not continue into polish. -- **Verb shouldn't have run** (Absolute bans present, no decoration to remove, no focal moment, etc.). Skip the standard run summary entirely. Surface a short refusal that names the reason and routes to the right alternative verb. Each per-verb reference's "When `` is the right verb (and when it isn't)" section enumerates the verb's specific refusal conditions. +Variant rules: -Tone is conversational. Lead with what changed, not with a banner. Don't capitalise words for emphasis. Don't print a ` pass complete ·` header — the summary's content is the proof of completion. +- **Fallback context:** name the source once (project instructions, README/docs, seed, or Clean) and nudge `/visualize teach`. Follow Brand profile's fallback hierarchy. +- **Diff >40%:** stop, report the scope, and apply Design judgment to recommend exploration if direction is unresolved or fresh creation if established. Do not continue to polish. +- **Verb shouldn't have run:** use the reference's refusal conditions; replace the standard summary with a short reason and the appropriate alternative. For `animate` specifically: when the brand declares `motion: none`, a fifth variant applies — see `reference/animate.md`. +Lead with changes, vary phrasing for the reader, and avoid fenced summaries, capitalized emphasis, or ` pass complete ·` banners. + ## Absolute bans Match-and-refuse. Apply on every command and the default creation flow. These ban specific patterns — not aesthetics, not registers. A brand can declare a font, a hue, or a layout that looks unusual; it cannot redeem any of these patterns by declaring them as identity. An explicit `.visualize-detect.json` skip can waive only a detector-backed ban with a concrete rule ID; it is project policy, not runtime brand suppression, and cannot waive a Layer-2 ban. @@ -191,21 +172,30 @@ These are not brand aesthetics; they are observed model reflexes with required c ## AI slop test (two altitudes) -Run both. The second catches what the first misses. +Run both tests: -**First-order**: if someone could guess the template + palette from the topic alone, you've hit the first training-data reflex. Topic stereotypes are prompts to inspect the brief, not color prohibitions: red, purple gradients, or navy-and-gold can fit a specific artifact. Rework unsupported defaults, not approved identity. +- **First-order:** could the topic alone predict the template and palette? Inspect unsupported stereotypes, not approved identity; hue names are not prohibitions. +- **Second-order:** could topic plus anti-references predict the aesthetic family? Avoid substituting another saturated reflex, such as cream/Georgia/margin-note editorial, mono/grid/heavy-border terminal, or uppercase/grotesk/grid Swiss-poster when the source and register do not support it. -**Second-order**: if someone could guess the aesthetic family from topic-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic," "fintech that's not navy-and-gold → terminal-native dark mode"), the second-tier reflex isn't avoided. Currently-saturated families to watch for: editorial-Tufte clone (cream + Georgia + side-margin notes when the topic isn't editorial), brutalist-terminal clone (mono + grid + heavy borders when the topic isn't dev-tool), Swiss-poster clone (uppercase + grotesk + grid when the topic isn't presentation). Rework until both altitudes return "no, you couldn't have guessed." +Rework unsupported defaults until neither test predicts the treatment; preserve approved identity. ## Brand profile -Every render reads available `DESIGN.md` (visual identity + design tokens) and `PRODUCT.md` (voice, audience, tone) at the project root. `teach` derives custom design tokens for the brand and writes them in `DESIGN.md` as YAML frontmatter (the Google Stitch canonical format: machine-readable tokens) plus a six-section markdown body (Overview / Colors / Typography / Elevation / Components / Do's and Don'ts), with a sidecar `tokens.css` at the project root carrying the CSS-form tokens templates read at render time. Project profiles retain concrete tokens, not a `theme: ` pointer. +Every render reads available project-root `DESIGN.md` (visual identity/tokens), `PRODUCT.md` (voice/audience/tone), and `tokens.css`. `teach` writes concrete project tokens in Stitch-format `DESIGN.md` plus the CSS sidecar, not a `theme: ` pointer; its schema and derivation procedure live in `reference/teach.md`. + +**Authority:** persisted `DESIGN.md` and `tokens.css` own visual tokens; `PRODUCT.md` owns voice and audience. Project instructions fill gaps without overriding persisted tokens unless the user explicitly says otherwise in the current request. Apply Artifact themes' approved exceptions before locking context. Brand authority is identity-scoped. If the request fixes a named identity but the resolved project profile clearly belongs to another product, do not substitute, relabel, or approximate it. Stop before the shape gate or any artifact edit and request matching authority or explicit permission for an artifact-only override. -The design systems under `design-systems/` are reference packages with design guidance, tokens, and previews. `teach` and System Explore read them when deriving project identities; artifact creation and exploration can use them as themes under the shared contract below. +`design-systems/` packages supply guidance, tokens, and previews for `teach`, System Explore, and artifact themes. + +**Fallback when no DESIGN.md exists:** + +1. Preserve an approved artifact reference as the baseline where project guidance is absent; do not replace it with a seed or Clean. +2. Otherwise read available project instructions (`AGENTS.md`, `CLAUDE.md`, README, docs) for positioning, visual direction, anti-references, and design principles. Treat usable guidance as binding brand context, including named fonts, palette roles, logo/mark rules, density/register, and anti-references, not optional mood. Follow referenced tokens, stylesheets, logo components, and guidelines before approximating from prose. Named fonts and palette roles override Clean's values; anti-references rule out the corresponding fallback register. Clean supplies the semantic token surface, not its fonts, monochrome palette, or warm/cream defaults. +3. Only with no usable visual direction, run `node $SKILL_DIR/scripts/palette.mjs --from ""`. Compose temporary primary, background, foreground, accent, chart, and state tokens from the seed and brief, using its `derived` contrast numbers, chroma budgets, and light/dark ladders. Do not estimate those values or copy Clean unchanged. If the seed fights the brief, re-run with `--not ` or `--vary ` and note the veto in the shape gate. Validate composed tokens with `node $SKILL_DIR/scripts/palette.mjs --check --strict`; fix errors (exit 2) before render. -**Fallback when no DESIGN.md exists:** an approved artifact reference supplies the visual baseline where project guidance is absent; do not replace it with a seed or Clean defaults. Otherwise, first read available project instructions (`AGENTS.md`, `CLAUDE.md`, README, docs) for product positioning, visual direction, anti-references, and design principles. If those files contain usable brand/design guidance, treat it as binding brand context while using Clean's token **surface** as the structural floor. Explicit cues in repo guidance override Clean values: named fonts become the artifact font stack, named palette roles become the artifact color tokens, and named anti-references rule out the corresponding fallback register. If the guidance points at concrete token files, stylesheet files, logo components, or design guidelines, read those referenced files and use their values before approximating from prose. Using Clean's token surface means keeping the semantic variable shape, not copying Clean's fonts, monochrome values, or warm/cream defaults. Only run `node $SKILL_DIR/scripts/palette.mjs --from ""` when the project has no usable visual direction at all. When a seed is used, compose the temporary `--primary`, `--background`, `--foreground`, `--accent`, chart, and state tokens from the seed + artifact brief; do not copy Clean's monochrome palette unchanged. Use the script's `derived` block (real contrast numbers, per-hue chroma budgets, light + dark lightness ladders) instead of estimating those values; if the seed's register fights the brief, re-run with `--not ` or `--vary ` and note the veto in the shape gate. After composing, validate with `node $SKILL_DIR/scripts/palette.mjs --check --strict` and fix error findings (exit 2) before render. Nudge `/visualize teach` once per session so repo guidance or the temporary seed can become a real brand profile. +Nudge `/visualize teach` once per session when using fallback context. **Refine verbs on missing persisted brand files:** `simplify` / `bolder` / `quieter` / `animate` / `polish` use the same fallback hierarchy as creation. Project instructions, README/docs, or other already-loaded context can be a valid qualitative brand anchor. Clean defaults are only the anchor when no usable project guidance exists. Whenever a fallback source is used, mention that source once and nudge `/visualize teach` so the fallback can become a real brand profile. @@ -213,15 +203,15 @@ The design systems under `design-systems/` are reference packages with design gu ## Artifact themes -A theme is a reference design system applied to one artifact, not a new stored object or a project-wide adoption. Use the current project system by default. Resolve binding project choices, approved artifact exceptions, and open design dimensions before borrowing from a reference. A named reference or a request to make an artifact more expressive does not silently override binding project choices; clarify conflicts that the request leaves unresolved. Explicit permission to replace visual styling applies only to the named artifact and dimensions. Do not invent constraints where the project is silent. +A theme is a reference design system applied to one artifact, not a new stored object or a project-wide adoption. Default to the project system; resolve binding choices, approved exceptions, and open dimensions before borrowing. A named reference or request for more expression does not silently override binding choices. Clarify unresolved conflicts; explicit replacement permission covers only the named artifact and dimensions. Do not invent constraints where the project is silent. -Read the selected `design-systems//README.md` when present, then its `DESIGN.md` and `tokens.css`. README is the package entry point; DESIGN owns suitability, identity, and adaptation guidance. Use previews to understand the treatment, not as required layouts. If the user wants alternatives, propose a small relevant shortlist rather than loading the entire catalog. A missing README does not make a package unavailable. +Read the selected package's `README.md` when present, then `DESIGN.md` and `tokens.css`. DESIGN owns suitability, identity, and adaptation. Previews illustrate treatment, not required layouts. When the user wants alternatives, offer a small relevant shortlist; do not load the whole catalog. A missing README does not make a package unavailable. -Apply a named treatment through ordinary creation or revision; compare unresolved treatments through `explore artifact`. Neither requires a new layout or a project profile first. For new content, derive structure from the reader's task and source. For existing artifacts, preserve content, order, assets, and behavior unless those changes were requested. A broad restyling uses `reference/create.md` with that preservation scope, not a narrow refine verb forced past its diff guard. Existing approval gates still apply; an explicit request already covering the proposed changes does not need reconfirmation. +Apply a treatment through creation or revision; compare unresolved treatments through `explore artifact`. Neither requires a new layout or project profile. Derive new structure from source and reader task. Preserve existing content, order, assets, and behavior unless changes were requested. Broad restyling uses `reference/create.md` with that scope rather than exceeding a refine verb's diff guard. Existing approval gates apply; an explicit request covering the proposed changes needs no reconfirmation. -Translate the reference's hierarchy, spacing, surfaces, and component treatment as well as its palette and type. Keep non-overridden project choices. Embed the resolved tokens, including designed light/dark and OS-dark behavior, in the artifact; do not replace the project's token source. Verify against the resolved artifact context, not the overridden project values. Describe partial borrowing and retained constraints rather than claiming an unchanged reference application. Keep the approved exception and its scope in existing task notes or a short artifact comment so later refinement can preserve it; unexplained styling drift alone is not approval. +Translate hierarchy, spacing, surfaces, and component treatment alongside palette and type. Preserve non-overridden project choices. Embed resolved tokens with light, explicit-dark, and OS-dark behavior in the artifact; do not replace the project's token source. Verify against the resolved artifact context, not overridden values. Describe partial borrowing and retained constraints accurately. Record approved exceptions and scope in existing task notes or a short artifact comment for later refinement; unexplained drift is not approval. -For project-wide capture or direct derivation, use `teach`. To compare new or explicitly requested replacement systems, use `explore system`. Neither route is a prerequisite for artifact themes. +Project-wide capture or derivation uses `teach`; comparing new or explicitly requested replacement systems uses `explore system`. Neither is a prerequisite for artifact themes. ## Universal laws diff --git a/skills/visualize/reference/create.md b/skills/visualize/reference/create.md index b163aa4..b8d194b 100644 --- a/skills/visualize/reference/create.md +++ b/skills/visualize/reference/create.md @@ -10,7 +10,7 @@ Autonomous harnesses (Codex-class) have been observed jumping to file writes bef Before composing, confirm: -1. **Context loaded.** Resolve artifact context, brand/context source, token source, and fallback behavior per SKILL.md before choosing a template or writing code. If fallback context is used because `DESIGN.md` / `PRODUCT.md` are absent, extract binding brand cues from project instructions: named fonts, palette roles, logo/mark rules, density/register, and anti-references. If those instructions cite token files, stylesheets, design guidelines, or logo components, read those files before composing. Do not treat those cues as optional mood. **Brand-source precedence when sources disagree:** persisted `DESIGN.md` and `tokens.css` win for visual tokens (colors, fonts, surfaces); `PRODUCT.md` wins for voice and audience; fallback project instructions fill gaps but do not override persisted brand tokens unless the user explicitly says so in the current request. Apply SKILL.md's Artifact themes contract before locking the visual context; approved artifact exceptions participate in that resolution. +1. **Context loaded.** Resolve context and tokens using SKILL.md's Brand profile and Artifact themes contracts, including fallback sources, their referenced assets, and approved exceptions, before choosing a template or writing code. 2. **Brand-fidelity lock.** From the artifact context resolved in step 1, record the applicable invariants across the categories below. These are enforceable, not aspirational. Do not invent invariants where the brand profile is silent — absence is a valid answer for any individual category. - **Named fonts.** If the brand profile or fallback source names specific fonts, those fonts must lead the body / heading / code CSS stacks in the artifact. `system-ui`, `Inter`, `-apple-system`, or any other generic sans cannot lead the stack unless the brand explicitly names them. - **Named palette / color system.** If the brand profile names palette roles or uses a specific color system (OKLCH, `color-mix`, `lab`, `lch`), `--background` / `--foreground` / `--primary` / borders / surfaces must derive from that palette and use that color system, not from fallback cream-paper, generic grays, or seed-generated hues. @@ -25,7 +25,7 @@ Before composing, confirm: - `deck` — slide or presentation sequence where each screen is consumed separately. Mode describes consumption, not aesthetic register. A `document` can still use product-native, application-like, spatial, editorial, or technical-drawing grammar when that grammar expresses the source and brand. Do not let the conservative mode default choose the artifact's look for you. -5. **Template picked.** Select from `templates/*/template.md` using template name, description, Use when, and Do not use when. Templates are starting points, not fixed artifact shells: customize the chosen template to fit the reader job and source, then fall back to pattern recipes for recurring structures the template does not cover. Template names are weak evidence; required structure and reader job are strong evidence. Pick the most specific template only when its required structure fits the source without inventing missing fields. If a named template would force a time axis, live-status semantics, escalation path, operational checks, slide sequence, scoring model, or other content the source does not provide, choose the broader document template and borrow only bounded primitives. Bounded primitives are small structures inside the chosen mode — e.g. labeled time-window rows, status marks, compact scenario tables, one contained topology figure — not the named template's full chrome or layout system. State the choice with one-line rationale. +5. **Template picked.** Start candidate selection from the name, description, Use when, and Do not use when sections of `templates/*/template.md`. Read further candidate sections only when needed to resolve uncertainty about structural fit. Templates are starting points, not fixed artifact shells: customize the chosen template to fit the reader job and source, then fall back to pattern recipes for recurring structures the template does not cover. Template names are weak evidence; required structure and reader job are strong evidence. Pick the most specific template only when its required structure fits the source without inventing missing fields. If a named template would force a time axis, live-status semantics, escalation path, operational checks, slide sequence, scoring model, or other content the source does not provide, choose the broader document template and borrow only bounded primitives. Bounded primitives are small structures inside the chosen mode — e.g. labeled time-window rows, status marks, compact scenario tables, one contained topology figure — not the named template's full chrome or layout system. State the choice with one-line rationale. 6. **Composition reflex check.** Before sketching shape, name up to three artifact-class defaults you must NOT assume — at least one when an obvious reflex exists for the class. The defaults are moves that appear across every AI-generated version of this artifact class regardless of source or brand — the median answer to the class's prompt. The reflex defaults for any artifact class tend to cluster around the dominant masthead pattern, the default section rhythm, the default verdict/answer placement, and the default secondary-navigation device (TOC, sidebar, sticky chrome). Identify the ones that apply to the class at hand (up to three). diff --git a/skills/visualize/reference/polish.md b/skills/visualize/reference/polish.md index 2b17d2c..ce80dea 100644 --- a/skills/visualize/reference/polish.md +++ b/skills/visualize/reference/polish.md @@ -11,7 +11,7 @@ Walk every applicable quality dimension and report findings against the reader's Read in order: 1. **The artifact.** Open the file, scroll it end-to-end in your head. Notice what the eye lands on first, what feels off, what reads as "agent eyeballed it." -2. **The detector.** Run `node $SKILL_DIR/scripts/detect.mjs --json ` for the mechanical floor. Detector output is **defect-evidence**, never **done-evidence** — a clean result is not proof the artifact is strong. The detector catches what regex can identify; polish covers everything else. +2. **The detector.** Run `node $SKILL_DIR/scripts/detect.mjs --json ` for the mechanical floor; apply SKILL.md's Universal law 7 when interpreting the result. ## Discovery: name the root cause, not just the symptom @@ -170,7 +170,7 @@ Skipped verification accumulates as "polish reports clean but the artifact is br If the artifact needs broad rework, polish has misfired. The escape: -- **Artifact carries ≥3 Absolute bans** → refuse and route to `/visualize simplify` first. Simplify's job is removing ban patterns; polish assumes a clean baseline. (SKILL.md's "Refine verbs on artifacts that carry ≥3 Absolute bans" rule applies.) +- **Ban-heavy artifact** → apply SKILL.md's "Refine verbs on artifacts that carry ≥3 Absolute bans" refusal and routing contract. - **Artifact needs broad rework beyond polish** → stop refinement and apply SKILL.md's Hand-off output shape and Design judgment to recommend the next action. - **Do not hand off to another Refine verb expecting it to come back.** The Refine verbs (`simplify` / `bolder` / `quieter` / `animate`) hand off to polish, but polish doesn't hand off to them — that creates a cycle. When polish refuses, recommend the next action to the user; do not start another command. diff --git a/skills/visualize/reference/review.md b/skills/visualize/reference/review.md index cdc3f78..6ba6c9e 100644 --- a/skills/visualize/reference/review.md +++ b/skills/visualize/reference/review.md @@ -92,8 +92,7 @@ Things detect.mjs deliberately doesn't try to catch: register-dependence, vocab- - **Mock identity** beyond the obvious: fictitious customer quotes ("Sarah Johnson, VP Marketing"), placeholder phone / address / company / brand names that aren't in the obvious set (Acme, Globex, Anytown, TBD, XXX-XXX-XXXX). - **Slop openers**: "leverage / streamline / empower / unlock / elevate / unleash / robust / holistic / seamless / cutting-edge / next-gen / In conclusion / TL;DR:" packed into the opening paragraphs. -- **Sycophant footers**: "I hope you find this useful", "Happy to clarify", "Hopefully this addresses your needs", "Best, Claude", anything signed by an AI. -- **Imperative tricolon** ("Ship faster. Build smarter. Scale forever."): three commands ending in periods, regardless of content. Can't be redeemed. +- **Sycophant footers and imperative tricolons**: inspect against SKILL.md BAN 7 and BAN 6. **Brand- and register-dependent slop** (mechanical detector would false-positive). These judgment calls exclude SKILL.md's Absolute bans, which resolved context cannot redeem. When deciding the remaining calls, consult [color.md](color.md) / [typography.md](typography.md) / [spatial.md](spatial.md) / [copy.md](copy.md) for the deeper material: @@ -161,7 +160,7 @@ Context-suppressed detector results are audit evidence rather than actionable fi - **≥4 `slop/center-everything` declarations in a non-Bauhaus / non-academic register = pattern.** Single centered hero is fine. When unsure, default to surfacing it as info + naming the aggregate count. -- **Universal law 6**: the reader is the judge. Does each finding make the reader's job harder, or just satisfy a rule? +- Apply SKILL.md's Universal law 6 to every finding. ## Output format (mandatory shape) diff --git a/skills/visualize/templates/comparison/template.md b/skills/visualize/templates/comparison/template.md index 8ca488c..5afa071 100644 --- a/skills/visualize/templates/comparison/template.md +++ b/skills/visualize/templates/comparison/template.md @@ -1,17 +1,17 @@ --- name: Comparison -description: A decision-support artifact for comparing options, tradeoffs, and recommendations. +description: A qualitative options matrix with yes/no/partial/varies cell states, supporting values, and tradeoffs. --- # Comparison ## Use when -Use this template when the reader needs decision-support artifact for comparing options, tradeoffs, and recommendations. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use for one option-by-criterion matrix. Every cell carries both a state (`yes` / `no` / `partial` / `varies`) and a supporting value; explanations carry nuance. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +For numeric observations without an option-by-criterion evaluation, use Report with an ordinary table. Split multiple comparison matrices into separate artifacts or use Report with embedded comparison figures. ## Structure @@ -37,9 +37,9 @@ The first two phone screens must deliver title, thesis, and essential context wi ## Failure modes -**Single-table rule.** Exactly one `
` per artifact. A second `cmp-table` block trips the detector — multi-table comparisons fragment the read; split them into multiple Comparison artifacts or fold into a Report with embedded comparison figures. +**Single-table rule.** Render the matrix as `
`. A second `cmp-table` block trips the detector because multi-table comparisons fragment the read. -**Cell-state vocabulary is closed.** States are drawn from `yes` / `no` / `partial` / `varies` — full stop. Inventing new states (`coming-soon`, `beta`, `enterprise-only`) trips the detector because they erode the scan-at-a-glance property the closed vocabulary buys. Encode nuance in the cell's `detail` text, not in a new state. Every cell carries both a `state` and a `value`; a blank cell is a content gap, not a styling choice. +**Invalid cell states.** Inventing states (`coming-soon`, `beta`, `enterprise-only`) outside the selection vocabulary trips the detector because they erode the scan-at-a-glance property the closed vocabulary buys. Encode nuance in the cell's `detail` text, not in a new state. A blank cell is a content gap, not a styling choice. **Us-column singularity.** Exactly one column may carry `isUs: true` (zero is valid for a neutral comparison; two or more is positioning incoherence — "us" is a singular concept). The emphasis is a quiet `--us-band-bg` + foreground-derived border, never a brand-primary fill — a brand-coloured us-column opts out of the restraint that makes the comparison read as honest. diff --git a/skills/visualize/templates/report/template.md b/skills/visualize/templates/report/template.md index 2597462..2909909 100644 --- a/skills/visualize/templates/report/template.md +++ b/skills/visualize/templates/report/template.md @@ -1,17 +1,17 @@ --- name: Report -description: A structured long-form artifact for explaining findings, context, implications, and next steps. +description: A prose-led document explaining findings, evidence, implications, and next actions, with supporting tables or figures. --- # Report ## Use when -Use this template when the reader needs structured long-form artifact for explaining findings, context, implications, and next steps. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use when the main job is explaining findings and next steps, with prose, ordinary numeric tables, or supporting figures. Fits short decision briefs as well as longer reports. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +Use Comparison for a qualitative option-by-criterion matrix, Research brief for research-source synthesis or study documentation, and a plain answer when the material needs no document structure. ## Structure diff --git a/skills/visualize/templates/research-brief/template.md b/skills/visualize/templates/research-brief/template.md index 7b0c66d..a0f70b4 100644 --- a/skills/visualize/templates/research-brief/template.md +++ b/skills/visualize/templates/research-brief/template.md @@ -1,17 +1,17 @@ --- name: Research brief -description: A concise evidence synthesis for a research question, market, user, or competitor. +description: A research-source synthesis or study write-up, with source provenance and study-specific disclosures when applicable. --- # Research brief ## Use when -Use this template when the reader needs concise evidence synthesis for a research question, market, user, or competitor. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use to answer a research question from market, competitor, desk-research, or primary user-research sources. Interview studies use the methodology and citation contracts below; secondary-source or desk-research briefs still need source trails and claim-level provenance, but not interview-specific sections. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +Use Report for operational findings and next steps that need no research-source synthesis or study documentation. Use a plain answer when the question needs no structured evidence synthesis. ## Structure @@ -27,7 +27,7 @@ Read pattern recipes only when the content calls for them: `metadata` for docume Prior visual variants are no longer live authoring files. If the ask needs a distinct register or rendering route, express that choice in the artifact-local composition and document the reason in visible copy only when it helps the reader. -Default to `document` mode for source synthesis, market scans, competitor reads, user research summaries, and other prose-led evidence briefs. Interview studies use the methodology and citation contracts below; secondary-source or desk-research briefs still need source trails and claim-level provenance, but not interview-specific sections. Use canvas/dashboard primitives only when relationships or metrics are the main read and the source material supplies the model. +Default to `document` mode for source synthesis, market scans, competitor reads, user research summaries, and other prose-led evidence briefs. Use canvas/dashboard primitives only when relationships or metrics are the main read and the source material supplies the model. ## Hierarchy contract diff --git a/visualize/SKILL.md b/visualize/SKILL.md index 35bd47a..06f3d6c 100644 --- a/visualize/SKILL.md +++ b/visualize/SKILL.md @@ -26,20 +26,12 @@ allowed-tools: - Bash(bash */visualize/scripts/publish.sh*) - Bash(*/visualize/scripts/publish.sh*) description: > - Generate beautiful, on-brand HTML artifacts — reports, diagrams, diff - reviews, slide decks, plans, recaps, dashboards. Loads on creation - intents ("create a plan", "make me an implementation plan", - "generate a diagram", "build a slide deck", "draft a recap", - "visualize this", "render this as HTML", "make me a status update") - and exploration intents ("show me three layouts", "explore document - shapes", "compare visual treatments", "explore a new design system", - "compare replacement brand directions") and iteration intents ("make this beautiful", "polish this report", - "make this less generic", "design this", "theme this", "use my - brand", "iterate on this design", "review this artifact", "make - this bolder", "make this quieter", "simplify this design", - "animate this", "improve the look of", "give this a refresh"). - Captures brand from the user's codebase, asking, or live site, then - applies it to every artifact. + Create, explore, refine, and review on-brand HTML reports, diagrams, + diff reviews, slide decks, plans, recaps, and dashboards. Use to visualize + information, compare layouts or design systems, apply a brand or theme, + or improve an artifact's design, including simplifying, polishing, making + it bolder or quieter, and animating. Capture brand from code, conversation, + or a live site. --- # visualize — beautiful, on-brand HTML artifacts @@ -48,25 +40,21 @@ Generate self-contained HTML artifacts composed from `templates/*/template.md` c ## Design judgment -Identify what the reader needs to understand, make the important distinction visible, and retain the evidence and qualifications needed to interpret it correctly. +Identify the reader's task and make the important distinction visible, retaining the evidence and qualifications needed to interpret it. Before choosing a treatment, find the source's organizing relationship, contrast, sequence, decision, or object; let it shape the opening, section rhythm, and explanatory primitives. When none helps, prefer restrained reading over a manufactured organizing idea. -Find the artifact's organizing idea before choosing its visual treatment. Look for a relationship, contrast, sequence, decision, or object in the source that the composition itself can make easier to understand. Use that idea to shape the opening, section rhythm, and any explanatory primitive. When the source has no useful spatial or structural idea, prefer a restrained reading experience over manufacturing one. - -Artifact mode describes how the reader consumes the information, not the aesthetic family it must use. A document can use product-native, application-like, spatial, editorial, or technical-drawing grammar when that grammar serves the source, reader, and brand. Do not equate `document` with editorial publishing, or `canvas` with diagram chrome. - -Visual conviction can come from composition, typography, density, spatial rhythm, imagery, interaction, or color. Do not add hues, decoration, or components merely to make an artifact feel designed. A restrained palette can carry a strong point of view when another dimension does the expressive work. +Artifact mode describes consumption, not aesthetics: `document` need not mean editorial publishing, nor `canvas` diagram chrome. Composition, typography, density, spatial rhythm, imagery, interaction, or color can supply conviction. Do not add hues, decoration, or components merely to make the artifact feel designed. Before responding to feedback, compare the observation with the artifact's reader, purpose, source, and approved brief where one exists. Distinguish an implementation defect, a design that fails its existing requirements, and evidence that a requirement or assumption has changed. The current composition is a solution, not a constraint. Make authorized corrections within the existing brief directly. If feedback implies a change to established requirements that the user has not already approved, explain the proposed change and obtain agreement before editing. When several structural or visual directions remain plausible, recommend `explore artifact` within its supported scope. When the direction is established, use the ordinary creation or refinement workflow. Follow that workflow's approval requirements; a small correction does not need a new exploration. -Evaluate proposed fixes together against the reader's task. Do not turn every critique finding into an addition or treat a small diff as evidence that the direction is sound. Preserve decision-relevant deferred observations in existing review or task notes. +Judge proposed fixes together against the reader's task. Do not turn every critique finding into an addition or treat a small diff as evidence of a sound direction. Retain decision-relevant deferred observations in existing review or task notes. ## Commands -`{{command_prefix}}visualize` invokes the skill. The argument tells the agent what to do. +`{{command_prefix}}visualize` takes a command or topic/path. -**Default (no command, or the first argument is a topic):** `{{command_prefix}}visualize ` creates a new artifact. The agent picks a template from intent across all of `templates/`, composes against the resolved project or artifact-theme context, writes self-contained HTML. **The flow is gated:** preflight checklist + shape-gate before code, no self-authored briefs. See `reference/create.md`. +**Default (topic/path without a command):** create self-contained HTML using a template and resolved context. Read `reference/create.md`; preflight and user-approved shape precede code. An agent-authored brief cannot approve itself. **Named commands:** @@ -82,12 +70,12 @@ Evaluate proposed fixes together against the reader's task. Do not turn every cr | **Evaluate** | `review` | `` | Deterministic detector findings + LLM judgment. Reports; doesn't modify the file. | `reference/review.md` | | **Publish** | `publish` | `` | Push the artifact to display.dev via MCP / CLI / HTTP cascade. | `reference/publish.md` | -Invocation forms: `{{command_prefix}}visualize teach`, `{{command_prefix}}visualize explore artifact ./report.html`, `{{command_prefix}}visualize polish ./report.html`, `{{command_prefix}}visualize publish ./diagram.html`. On hosts without a slash-command form, the skill loads on intent-match from the description above; natural-language is the primary entry there. +Example: `{{command_prefix}}visualize polish ./report.html`. On hosts without slash commands, natural-language intent is the primary entry. ## Routing rules 1. **No argument**: render the Commands table above as the user-facing menu, grouped by category. Ask what they'd like to do. -2. **First word matches a command**: **load its reference file before doing anything else.** Non-negotiable — the table row + this section is insufficient; the procedure lives in the reference. Everything after the command name is the target. +2. **First word matches a command**: **load its reference before acting**; the table is not the procedure. Everything after the command name is the target. 3. **Natural-language intent**: requests to compare design alternatives load `reference/explore.md`; capturing or reconciling project identity loads `reference/teach.md`. Otherwise load `reference/create.md` for creation or an explicitly requested restyling of an existing artifact. A named theme follows Artifact themes below; it does not require an exploration round. 4. **Relationship-diagram route during creation**: when preflight first identifies a likely relationship diagram, load `reference/diagram.md` and the one tentative non-spatial type reference needed for that figure before presenting the shape gate. For multi-figure artifacts, load one reference for each distinct tentative family: `reference/diagram-flow.md`, `reference/diagram-system.md`, `reference/diagram-sequence.md`, `reference/diagram-state.md`, or `reference/diagram-hierarchy.md`. Spatial figures use `reference/diagram.md` alone. If approval changes a figure's type, load the replacement reference before authoring; do not load unrelated families. 5. **Generated-image route during creation**: when the approved shape requires generated bitmap imagery, load `reference/image-generation.md` before selecting or invoking a route. Use only the active callable inventory or an explicitly selected API adapter. Never infer a route from a key, executable, mount, or model claim, and never retry or fall back after an ambiguous attempt. @@ -95,25 +83,18 @@ Invocation forms: `{{command_prefix}}visualize teach`, `{{command_prefix}}visual ## Hand-off output shape -After a refine verb (`simplify` / `bolder` / `quieter` / `animate`) finishes its run, summarise to the user in plain markdown. Don't render the summary as a fenced code block — it's conversational output, not machine-readable. Vary phrasing across runs; pick wording per context (engineer reading detector output vs. designer iterating on a brand brief). `polish` has its own output shape — see `reference/polish.md`. - -Every refine run's summary covers four facts: - -- Which verb ran, against which artifact. -- What the verb actually did. Pull the verb-specific content from the per-verb reference's "what to surface" list (focal moment, cuts + audit trail, strategy, what stayed, hero moment, reduced-motion handling — depends on the verb). -- Diff size as a percent of the artifact. -- Which next action makes sense, if any. Polish is the default next step from a successful refine run. - -Variant rules (behaviour, not surface text): +After `simplify` / `bolder` / `quieter` / `animate`, report in conversational markdown: verb and target, changes drawn from the reference's "what to surface" list, diff percentage, and the appropriate next action. Successful refinement defaults to `polish`, which has its own output shape in `reference/polish.md`. -- **Context source note.** If the run cannot use a persisted `DESIGN.md` / `PRODUCT.md`, mention once which fallback source anchored the work: project instructions, README/docs, generated seed, or Clean defaults. Also nudge the user to run `{{command_prefix}}visualize teach` so that fallback can become a real brand profile. Clean defaults are the last resort after the Brand profile rules below find no usable project guidance. -- **Diff exceeded the 40% guard.** Stop refinement and report the affected scope. Apply Design judgment to recommend exploration when the structural direction remains unresolved, or a fresh creation pass when it is established. Do not continue into polish. -- **Verb shouldn't have run** (Absolute bans present, no decoration to remove, no focal moment, etc.). Skip the standard run summary entirely. Surface a short refusal that names the reason and routes to the right alternative verb. Each per-verb reference's "When `` is the right verb (and when it isn't)" section enumerates the verb's specific refusal conditions. +Variant rules: -Tone is conversational. Lead with what changed, not with a banner. Don't capitalise words for emphasis. Don't print a ` pass complete ·` header — the summary's content is the proof of completion. +- **Fallback context:** name the source once (project instructions, README/docs, seed, or Clean) and nudge `{{command_prefix}}visualize teach`. Follow Brand profile's fallback hierarchy. +- **Diff >40%:** stop, report the scope, and apply Design judgment to recommend exploration if direction is unresolved or fresh creation if established. Do not continue to polish. +- **Verb shouldn't have run:** use the reference's refusal conditions; replace the standard summary with a short reason and the appropriate alternative. For `animate` specifically: when the brand declares `motion: none`, a fifth variant applies — see `reference/animate.md`. +Lead with changes, vary phrasing for the reader, and avoid fenced summaries, capitalized emphasis, or ` pass complete ·` banners. + ## Absolute bans Match-and-refuse. Apply on every command and the default creation flow. These ban specific patterns — not aesthetics, not registers. A brand can declare a font, a hue, or a layout that looks unusual; it cannot redeem any of these patterns by declaring them as identity. An explicit `.visualize-detect.json` skip can waive only a detector-backed ban with a concrete rule ID; it is project policy, not runtime brand suppression, and cannot waive a Layer-2 ban. @@ -191,21 +172,30 @@ These are not brand aesthetics; they are observed model reflexes with required c ## AI slop test (two altitudes) -Run both. The second catches what the first misses. +Run both tests: -**First-order**: if someone could guess the template + palette from the topic alone, you've hit the first training-data reflex. Topic stereotypes are prompts to inspect the brief, not color prohibitions: red, purple gradients, or navy-and-gold can fit a specific artifact. Rework unsupported defaults, not approved identity. +- **First-order:** could the topic alone predict the template and palette? Inspect unsupported stereotypes, not approved identity; hue names are not prohibitions. +- **Second-order:** could topic plus anti-references predict the aesthetic family? Avoid substituting another saturated reflex, such as cream/Georgia/margin-note editorial, mono/grid/heavy-border terminal, or uppercase/grotesk/grid Swiss-poster when the source and register do not support it. -**Second-order**: if someone could guess the aesthetic family from topic-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic," "fintech that's not navy-and-gold → terminal-native dark mode"), the second-tier reflex isn't avoided. Currently-saturated families to watch for: editorial-Tufte clone (cream + Georgia + side-margin notes when the topic isn't editorial), brutalist-terminal clone (mono + grid + heavy borders when the topic isn't dev-tool), Swiss-poster clone (uppercase + grotesk + grid when the topic isn't presentation). Rework until both altitudes return "no, you couldn't have guessed." +Rework unsupported defaults until neither test predicts the treatment; preserve approved identity. ## Brand profile -Every render reads available `DESIGN.md` (visual identity + design tokens) and `PRODUCT.md` (voice, audience, tone) at the project root. `teach` derives custom design tokens for the brand and writes them in `DESIGN.md` as YAML frontmatter (the Google Stitch canonical format: machine-readable tokens) plus a six-section markdown body (Overview / Colors / Typography / Elevation / Components / Do's and Don'ts), with a sidecar `tokens.css` at the project root carrying the CSS-form tokens templates read at render time. Project profiles retain concrete tokens, not a `theme: ` pointer. +Every render reads available project-root `DESIGN.md` (visual identity/tokens), `PRODUCT.md` (voice/audience/tone), and `tokens.css`. `teach` writes concrete project tokens in Stitch-format `DESIGN.md` plus the CSS sidecar, not a `theme: ` pointer; its schema and derivation procedure live in `reference/teach.md`. + +**Authority:** persisted `DESIGN.md` and `tokens.css` own visual tokens; `PRODUCT.md` owns voice and audience. Project instructions fill gaps without overriding persisted tokens unless the user explicitly says otherwise in the current request. Apply Artifact themes' approved exceptions before locking context. Brand authority is identity-scoped. If the request fixes a named identity but the resolved project profile clearly belongs to another product, do not substitute, relabel, or approximate it. Stop before the shape gate or any artifact edit and request matching authority or explicit permission for an artifact-only override. -The design systems under `design-systems/` are reference packages with design guidance, tokens, and previews. `teach` and System Explore read them when deriving project identities; artifact creation and exploration can use them as themes under the shared contract below. +`design-systems/` packages supply guidance, tokens, and previews for `teach`, System Explore, and artifact themes. + +**Fallback when no DESIGN.md exists:** + +1. Preserve an approved artifact reference as the baseline where project guidance is absent; do not replace it with a seed or Clean. +2. Otherwise read available project instructions (`AGENTS.md`, `CLAUDE.md`, README, docs) for positioning, visual direction, anti-references, and design principles. Treat usable guidance as binding brand context, including named fonts, palette roles, logo/mark rules, density/register, and anti-references, not optional mood. Follow referenced tokens, stylesheets, logo components, and guidelines before approximating from prose. Named fonts and palette roles override Clean's values; anti-references rule out the corresponding fallback register. Clean supplies the semantic token surface, not its fonts, monochrome palette, or warm/cream defaults. +3. Only with no usable visual direction, run `node {{scripts_path}}/palette.mjs --from ""`. Compose temporary primary, background, foreground, accent, chart, and state tokens from the seed and brief, using its `derived` contrast numbers, chroma budgets, and light/dark ladders. Do not estimate those values or copy Clean unchanged. If the seed fights the brief, re-run with `--not ` or `--vary ` and note the veto in the shape gate. Validate composed tokens with `node {{scripts_path}}/palette.mjs --check --strict`; fix errors (exit 2) before render. -**Fallback when no DESIGN.md exists:** an approved artifact reference supplies the visual baseline where project guidance is absent; do not replace it with a seed or Clean defaults. Otherwise, first read available project instructions (`AGENTS.md`, `CLAUDE.md`, README, docs) for product positioning, visual direction, anti-references, and design principles. If those files contain usable brand/design guidance, treat it as binding brand context while using Clean's token **surface** as the structural floor. Explicit cues in repo guidance override Clean values: named fonts become the artifact font stack, named palette roles become the artifact color tokens, and named anti-references rule out the corresponding fallback register. If the guidance points at concrete token files, stylesheet files, logo components, or design guidelines, read those referenced files and use their values before approximating from prose. Using Clean's token surface means keeping the semantic variable shape, not copying Clean's fonts, monochrome values, or warm/cream defaults. Only run `node {{scripts_path}}/palette.mjs --from ""` when the project has no usable visual direction at all. When a seed is used, compose the temporary `--primary`, `--background`, `--foreground`, `--accent`, chart, and state tokens from the seed + artifact brief; do not copy Clean's monochrome palette unchanged. Use the script's `derived` block (real contrast numbers, per-hue chroma budgets, light + dark lightness ladders) instead of estimating those values; if the seed's register fights the brief, re-run with `--not ` or `--vary ` and note the veto in the shape gate. After composing, validate with `node {{scripts_path}}/palette.mjs --check --strict` and fix error findings (exit 2) before render. Nudge `{{command_prefix}}visualize teach` once per session so repo guidance or the temporary seed can become a real brand profile. +Nudge `{{command_prefix}}visualize teach` once per session when using fallback context. **Refine verbs on missing persisted brand files:** `simplify` / `bolder` / `quieter` / `animate` / `polish` use the same fallback hierarchy as creation. Project instructions, README/docs, or other already-loaded context can be a valid qualitative brand anchor. Clean defaults are only the anchor when no usable project guidance exists. Whenever a fallback source is used, mention that source once and nudge `{{command_prefix}}visualize teach` so the fallback can become a real brand profile. @@ -213,15 +203,15 @@ The design systems under `design-systems/` are reference packages with design gu ## Artifact themes -A theme is a reference design system applied to one artifact, not a new stored object or a project-wide adoption. Use the current project system by default. Resolve binding project choices, approved artifact exceptions, and open design dimensions before borrowing from a reference. A named reference or a request to make an artifact more expressive does not silently override binding project choices; clarify conflicts that the request leaves unresolved. Explicit permission to replace visual styling applies only to the named artifact and dimensions. Do not invent constraints where the project is silent. +A theme is a reference design system applied to one artifact, not a new stored object or a project-wide adoption. Default to the project system; resolve binding choices, approved exceptions, and open dimensions before borrowing. A named reference or request for more expression does not silently override binding choices. Clarify unresolved conflicts; explicit replacement permission covers only the named artifact and dimensions. Do not invent constraints where the project is silent. -Read the selected `design-systems//README.md` when present, then its `DESIGN.md` and `tokens.css`. README is the package entry point; DESIGN owns suitability, identity, and adaptation guidance. Use previews to understand the treatment, not as required layouts. If the user wants alternatives, propose a small relevant shortlist rather than loading the entire catalog. A missing README does not make a package unavailable. +Read the selected package's `README.md` when present, then `DESIGN.md` and `tokens.css`. DESIGN owns suitability, identity, and adaptation. Previews illustrate treatment, not required layouts. When the user wants alternatives, offer a small relevant shortlist; do not load the whole catalog. A missing README does not make a package unavailable. -Apply a named treatment through ordinary creation or revision; compare unresolved treatments through `explore artifact`. Neither requires a new layout or a project profile first. For new content, derive structure from the reader's task and source. For existing artifacts, preserve content, order, assets, and behavior unless those changes were requested. A broad restyling uses `reference/create.md` with that preservation scope, not a narrow refine verb forced past its diff guard. Existing approval gates still apply; an explicit request already covering the proposed changes does not need reconfirmation. +Apply a treatment through creation or revision; compare unresolved treatments through `explore artifact`. Neither requires a new layout or project profile. Derive new structure from source and reader task. Preserve existing content, order, assets, and behavior unless changes were requested. Broad restyling uses `reference/create.md` with that scope rather than exceeding a refine verb's diff guard. Existing approval gates apply; an explicit request covering the proposed changes needs no reconfirmation. -Translate the reference's hierarchy, spacing, surfaces, and component treatment as well as its palette and type. Keep non-overridden project choices. Embed the resolved tokens, including designed light/dark and OS-dark behavior, in the artifact; do not replace the project's token source. Verify against the resolved artifact context, not the overridden project values. Describe partial borrowing and retained constraints rather than claiming an unchanged reference application. Keep the approved exception and its scope in existing task notes or a short artifact comment so later refinement can preserve it; unexplained styling drift alone is not approval. +Translate hierarchy, spacing, surfaces, and component treatment alongside palette and type. Preserve non-overridden project choices. Embed resolved tokens with light, explicit-dark, and OS-dark behavior in the artifact; do not replace the project's token source. Verify against the resolved artifact context, not overridden values. Describe partial borrowing and retained constraints accurately. Record approved exceptions and scope in existing task notes or a short artifact comment for later refinement; unexplained drift is not approval. -For project-wide capture or direct derivation, use `teach`. To compare new or explicitly requested replacement systems, use `explore system`. Neither route is a prerequisite for artifact themes. +Project-wide capture or derivation uses `teach`; comparing new or explicitly requested replacement systems uses `explore system`. Neither is a prerequisite for artifact themes. ## Universal laws diff --git a/visualize/reference/create.md b/visualize/reference/create.md index 67eff18..f3eb3e9 100644 --- a/visualize/reference/create.md +++ b/visualize/reference/create.md @@ -10,7 +10,7 @@ Autonomous harnesses (Codex-class) have been observed jumping to file writes bef Before composing, confirm: -1. **Context loaded.** Resolve artifact context, brand/context source, token source, and fallback behavior per SKILL.md before choosing a template or writing code. If fallback context is used because `DESIGN.md` / `PRODUCT.md` are absent, extract binding brand cues from project instructions: named fonts, palette roles, logo/mark rules, density/register, and anti-references. If those instructions cite token files, stylesheets, design guidelines, or logo components, read those files before composing. Do not treat those cues as optional mood. **Brand-source precedence when sources disagree:** persisted `DESIGN.md` and `tokens.css` win for visual tokens (colors, fonts, surfaces); `PRODUCT.md` wins for voice and audience; fallback project instructions fill gaps but do not override persisted brand tokens unless the user explicitly says so in the current request. Apply SKILL.md's Artifact themes contract before locking the visual context; approved artifact exceptions participate in that resolution. +1. **Context loaded.** Resolve context and tokens using SKILL.md's Brand profile and Artifact themes contracts, including fallback sources, their referenced assets, and approved exceptions, before choosing a template or writing code. 2. **Brand-fidelity lock.** From the artifact context resolved in step 1, record the applicable invariants across the categories below. These are enforceable, not aspirational. Do not invent invariants where the brand profile is silent — absence is a valid answer for any individual category. - **Named fonts.** If the brand profile or fallback source names specific fonts, those fonts must lead the body / heading / code CSS stacks in the artifact. `system-ui`, `Inter`, `-apple-system`, or any other generic sans cannot lead the stack unless the brand explicitly names them. - **Named palette / color system.** If the brand profile names palette roles or uses a specific color system (OKLCH, `color-mix`, `lab`, `lch`), `--background` / `--foreground` / `--primary` / borders / surfaces must derive from that palette and use that color system, not from fallback cream-paper, generic grays, or seed-generated hues. @@ -25,7 +25,7 @@ Before composing, confirm: - `deck` — slide or presentation sequence where each screen is consumed separately. Mode describes consumption, not aesthetic register. A `document` can still use product-native, application-like, spatial, editorial, or technical-drawing grammar when that grammar expresses the source and brand. Do not let the conservative mode default choose the artifact's look for you. -5. **Template picked.** Select from `templates/*/template.md` using template name, description, Use when, and Do not use when. Templates are starting points, not fixed artifact shells: customize the chosen template to fit the reader job and source, then fall back to pattern recipes for recurring structures the template does not cover. Template names are weak evidence; required structure and reader job are strong evidence. Pick the most specific template only when its required structure fits the source without inventing missing fields. If a named template would force a time axis, live-status semantics, escalation path, operational checks, slide sequence, scoring model, or other content the source does not provide, choose the broader document template and borrow only bounded primitives. Bounded primitives are small structures inside the chosen mode — e.g. labeled time-window rows, status marks, compact scenario tables, one contained topology figure — not the named template's full chrome or layout system. State the choice with one-line rationale. +5. **Template picked.** Start candidate selection from the name, description, Use when, and Do not use when sections of `templates/*/template.md`. Read further candidate sections only when needed to resolve uncertainty about structural fit. Templates are starting points, not fixed artifact shells: customize the chosen template to fit the reader job and source, then fall back to pattern recipes for recurring structures the template does not cover. Template names are weak evidence; required structure and reader job are strong evidence. Pick the most specific template only when its required structure fits the source without inventing missing fields. If a named template would force a time axis, live-status semantics, escalation path, operational checks, slide sequence, scoring model, or other content the source does not provide, choose the broader document template and borrow only bounded primitives. Bounded primitives are small structures inside the chosen mode — e.g. labeled time-window rows, status marks, compact scenario tables, one contained topology figure — not the named template's full chrome or layout system. State the choice with one-line rationale. 6. **Composition reflex check.** Before sketching shape, name up to three artifact-class defaults you must NOT assume — at least one when an obvious reflex exists for the class. The defaults are moves that appear across every AI-generated version of this artifact class regardless of source or brand — the median answer to the class's prompt. The reflex defaults for any artifact class tend to cluster around the dominant masthead pattern, the default section rhythm, the default verdict/answer placement, and the default secondary-navigation device (TOC, sidebar, sticky chrome). Identify the ones that apply to the class at hand (up to three). diff --git a/visualize/reference/polish.md b/visualize/reference/polish.md index 0881054..85bd66f 100644 --- a/visualize/reference/polish.md +++ b/visualize/reference/polish.md @@ -11,7 +11,7 @@ Walk every applicable quality dimension and report findings against the reader's Read in order: 1. **The artifact.** Open the file, scroll it end-to-end in your head. Notice what the eye lands on first, what feels off, what reads as "agent eyeballed it." -2. **The detector.** Run `node {{scripts_path}}/detect.mjs --json ` for the mechanical floor. Detector output is **defect-evidence**, never **done-evidence** — a clean result is not proof the artifact is strong. The detector catches what regex can identify; polish covers everything else. +2. **The detector.** Run `node {{scripts_path}}/detect.mjs --json ` for the mechanical floor; apply SKILL.md's Universal law 7 when interpreting the result. ## Discovery: name the root cause, not just the symptom @@ -170,7 +170,7 @@ Skipped verification accumulates as "polish reports clean but the artifact is br If the artifact needs broad rework, polish has misfired. The escape: -- **Artifact carries ≥3 Absolute bans** → refuse and route to `{{command_prefix}}visualize simplify` first. Simplify's job is removing ban patterns; polish assumes a clean baseline. (SKILL.md's "Refine verbs on artifacts that carry ≥3 Absolute bans" rule applies.) +- **Ban-heavy artifact** → apply SKILL.md's "Refine verbs on artifacts that carry ≥3 Absolute bans" refusal and routing contract. - **Artifact needs broad rework beyond polish** → stop refinement and apply SKILL.md's Hand-off output shape and Design judgment to recommend the next action. - **Do not hand off to another Refine verb expecting it to come back.** The Refine verbs (`simplify` / `bolder` / `quieter` / `animate`) hand off to polish, but polish doesn't hand off to them — that creates a cycle. When polish refuses, recommend the next action to the user; do not start another command. diff --git a/visualize/reference/review.md b/visualize/reference/review.md index 2ef510f..749424c 100644 --- a/visualize/reference/review.md +++ b/visualize/reference/review.md @@ -92,8 +92,7 @@ Things detect.mjs deliberately doesn't try to catch: register-dependence, vocab- - **Mock identity** beyond the obvious: fictitious customer quotes ("Sarah Johnson, VP Marketing"), placeholder phone / address / company / brand names that aren't in the obvious set (Acme, Globex, Anytown, TBD, XXX-XXX-XXXX). - **Slop openers**: "leverage / streamline / empower / unlock / elevate / unleash / robust / holistic / seamless / cutting-edge / next-gen / In conclusion / TL;DR:" packed into the opening paragraphs. -- **Sycophant footers**: "I hope you find this useful", "Happy to clarify", "Hopefully this addresses your needs", "Best, Claude", anything signed by an AI. -- **Imperative tricolon** ("Ship faster. Build smarter. Scale forever."): three commands ending in periods, regardless of content. Can't be redeemed. +- **Sycophant footers and imperative tricolons**: inspect against SKILL.md BAN 7 and BAN 6. **Brand- and register-dependent slop** (mechanical detector would false-positive). These judgment calls exclude SKILL.md's Absolute bans, which resolved context cannot redeem. When deciding the remaining calls, consult [color.md](color.md) / [typography.md](typography.md) / [spatial.md](spatial.md) / [copy.md](copy.md) for the deeper material: @@ -161,7 +160,7 @@ Context-suppressed detector results are audit evidence rather than actionable fi - **≥4 `slop/center-everything` declarations in a non-Bauhaus / non-academic register = pattern.** Single centered hero is fine. When unsure, default to surfacing it as info + naming the aggregate count. -- **Universal law 6**: the reader is the judge. Does each finding make the reader's job harder, or just satisfy a rule? +- Apply SKILL.md's Universal law 6 to every finding. ## Output format (mandatory shape) diff --git a/visualize/templates/comparison/template.md b/visualize/templates/comparison/template.md index 8ca488c..5afa071 100644 --- a/visualize/templates/comparison/template.md +++ b/visualize/templates/comparison/template.md @@ -1,17 +1,17 @@ --- name: Comparison -description: A decision-support artifact for comparing options, tradeoffs, and recommendations. +description: A qualitative options matrix with yes/no/partial/varies cell states, supporting values, and tradeoffs. --- # Comparison ## Use when -Use this template when the reader needs decision-support artifact for comparing options, tradeoffs, and recommendations. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use for one option-by-criterion matrix. Every cell carries both a state (`yes` / `no` / `partial` / `varies`) and a supporting value; explanations carry nuance. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +For numeric observations without an option-by-criterion evaluation, use Report with an ordinary table. Split multiple comparison matrices into separate artifacts or use Report with embedded comparison figures. ## Structure @@ -37,9 +37,9 @@ The first two phone screens must deliver title, thesis, and essential context wi ## Failure modes -**Single-table rule.** Exactly one `
` per artifact. A second `cmp-table` block trips the detector — multi-table comparisons fragment the read; split them into multiple Comparison artifacts or fold into a Report with embedded comparison figures. +**Single-table rule.** Render the matrix as `
`. A second `cmp-table` block trips the detector because multi-table comparisons fragment the read. -**Cell-state vocabulary is closed.** States are drawn from `yes` / `no` / `partial` / `varies` — full stop. Inventing new states (`coming-soon`, `beta`, `enterprise-only`) trips the detector because they erode the scan-at-a-glance property the closed vocabulary buys. Encode nuance in the cell's `detail` text, not in a new state. Every cell carries both a `state` and a `value`; a blank cell is a content gap, not a styling choice. +**Invalid cell states.** Inventing states (`coming-soon`, `beta`, `enterprise-only`) outside the selection vocabulary trips the detector because they erode the scan-at-a-glance property the closed vocabulary buys. Encode nuance in the cell's `detail` text, not in a new state. A blank cell is a content gap, not a styling choice. **Us-column singularity.** Exactly one column may carry `isUs: true` (zero is valid for a neutral comparison; two or more is positioning incoherence — "us" is a singular concept). The emphasis is a quiet `--us-band-bg` + foreground-derived border, never a brand-primary fill — a brand-coloured us-column opts out of the restraint that makes the comparison read as honest. diff --git a/visualize/templates/report/template.md b/visualize/templates/report/template.md index c0ba3b7..ce2fbfa 100644 --- a/visualize/templates/report/template.md +++ b/visualize/templates/report/template.md @@ -1,17 +1,17 @@ --- name: Report -description: A structured long-form artifact for explaining findings, context, implications, and next steps. +description: A prose-led document explaining findings, evidence, implications, and next actions, with supporting tables or figures. --- # Report ## Use when -Use this template when the reader needs structured long-form artifact for explaining findings, context, implications, and next steps. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use when the main job is explaining findings and next steps, with prose, ordinary numeric tables, or supporting figures. Fits short decision briefs as well as longer reports. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +Use Comparison for a qualitative option-by-criterion matrix, Research brief for research-source synthesis or study documentation, and a plain answer when the material needs no document structure. ## Structure diff --git a/visualize/templates/research-brief/template.md b/visualize/templates/research-brief/template.md index 7b0c66d..a0f70b4 100644 --- a/visualize/templates/research-brief/template.md +++ b/visualize/templates/research-brief/template.md @@ -1,17 +1,17 @@ --- name: Research brief -description: A concise evidence synthesis for a research question, market, user, or competitor. +description: A research-source synthesis or study write-up, with source provenance and study-specific disclosures when applicable. --- # Research brief ## Use when -Use this template when the reader needs concise evidence synthesis for a research question, market, user, or competitor. Pick it when the artifact has enough substance to benefit from the named structure, not just because the topic contains similar words. +Use to answer a research question from market, competitor, desk-research, or primary user-research sources. Interview studies use the methodology and citation contracts below; secondary-source or desk-research briefs still need source trails and claim-level provenance, but not interview-specific sections. ## Do not use when -Do not use this when a simpler memo, plain prose answer, or a more specific template would make the reader faster. Do not force the template when the ask lacks the evidence or structure it requires. +Use Report for operational findings and next steps that need no research-source synthesis or study documentation. Use a plain answer when the question needs no structured evidence synthesis. ## Structure @@ -27,7 +27,7 @@ Read pattern recipes only when the content calls for them: `metadata` for docume Prior visual variants are no longer live authoring files. If the ask needs a distinct register or rendering route, express that choice in the artifact-local composition and document the reason in visible copy only when it helps the reader. -Default to `document` mode for source synthesis, market scans, competitor reads, user research summaries, and other prose-led evidence briefs. Interview studies use the methodology and citation contracts below; secondary-source or desk-research briefs still need source trails and claim-level provenance, but not interview-specific sections. Use canvas/dashboard primitives only when relationships or metrics are the main read and the source material supplies the model. +Default to `document` mode for source synthesis, market scans, competitor reads, user research summaries, and other prose-led evidence briefs. Use canvas/dashboard primitives only when relationships or metrics are the main read and the source material supplies the model. ## Hierarchy contract