@ericrisco/rsc 1.0.32 → 1.0.34

package/README.md

@@ -378,7 +378,7 @@ Three engines + engine-agnostic disciplines. Every engine skill pins the current
 
 ### 🎨 Design & content craft
 
-[design](skills/design/) · [presentations](skills/presentations/) · [course-storytelling](skills/course-storytelling/) · [course-builder](skills/course-builder/) · [technical-writing](skills/technical-writing/) · [translation-l10n](skills/translation-l10n/)
+[design-loop](skills/design-loop/) · [design](skills/design/) · [design-dna](skills/design-dna/) · [presentations](skills/presentations/) · [course-storytelling](skills/course-storytelling/) · [course-builder](skills/course-builder/) · [technical-writing](skills/technical-writing/) · [translation-l10n](skills/translation-l10n/)
 
 ### 🧠 Knowledge & meta
 

package/manifest.json

@@ -1,7 +1,7 @@
 {
-  "version": "1.0.32",
+  "version": "1.0.34",
   "counts": {
-    "skills": 276
+    "skills": 278
   },
   "skills": [
     {
@@ -1404,6 +1404,27 @@
         "conversion"
       ],
       "recommends": [
+        "design-loop",
+        "design-dna",
+        "nextjs",
+        "marketing"
+      ],
+      "profiles": []
+    },
+    {
+      "id": "design-dna",
+      "description": "Use when a design has won and its look must survive: codify it into a permanent style skill with measured ratios, bans and tests that can fail, then build new pieces in that exact look. Fires on 'turn this into a skill', 'keep the same style', 'my output drifted'. NOT finding the winner (that is `design-loop`), NOT the words (that is `marketing`).",
+      "tags": [
+        "design",
+        "style",
+        "dna",
+        "codify",
+        "skill-factory",
+        "consistency"
+      ],
+      "recommends": [
+        "design-loop",
+        "design",
         "nextjs",
         "marketing"
       ],
@@ -1420,6 +1441,7 @@
         "craft"
       ],
       "recommends": [
+        "design-loop",
         "animate",
         "review-animations",
         "apple-design",
@@ -1430,6 +1452,25 @@
         "full"
       ]
     },
+    {
+      "id": "design-loop",
+      "description": "Use when something must be built well and there is a real reference it should beat: turn what makes the reference good into measured mechanisms, then run a builder and three fresh-context critics until all three pass. Fires on 'design loop', 'make it as good as <site>', 'it looks generic'. NOT keeping an already-won look (that is `design-dna`).",
+      "tags": [
+        "design",
+        "critique",
+        "loop",
+        "reference",
+        "quality",
+        "convergence"
+      ],
+      "recommends": [
+        "design",
+        "design-dna",
+        "marketing",
+        "nextjs"
+      ],
+      "profiles": []
+    },
     {
       "id": "digitalocean",
       "description": "Use when deploying or operating a workload on DigitalOcean — Droplet vs App Platform vs Functions, doctl, app spec YAML, Managed Postgres/MySQL/Valkey on the VPC, S3-compatible Spaces + CDN. NOT host-agnostic CI/CD or rollback strategy (that is `deployment`), NOT a bare Hetzner VPS (that is `hetzner`), NOT another managed PaaS (that is `railway`).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/doctor.js

@@ -93,32 +93,142 @@ function alwaysOnBytesFor(scopeRoot, settingsRaw) {
   return bytesOf(join(scopeRoot, '.rsc', 'skills', 'suggest', 'SKILL.md'));
 }
 
+// Every hook rsc wires, as a table rather than a chain of `if`s: adding one is a row, and
+// tests/doctor-hook-counts.test.js iterates it, so a hook added without a row fails the suite instead
+// of shipping uncounted. `needle` is the SCRIPT PATH, never the bare `.rsc` — a user's own hook that
+// merely mentions the directory must not be counted as ours.
+//
+// `injects` marks the two hooks that put text into the conversation. It matters because a duplicated
+// guard costs processes, not bytes, and conflating the two is how this report lied in the first place.
+export const RSC_HOOKS = [
+  { id: 'session-start', label: 'session-start', needle: '.rsc/session-start.', injects: 'sessionStart' },
+  { id: 'userprompt-gate', label: 'userprompt-gate', needle: '.rsc/userprompt-gate.', injects: 'perTurn' },
+  { id: 'worklog-checkpoint', label: 'worklog-checkpoint', needle: '.rsc/worklog-checkpoint.', injects: null },
+  { id: 'ship-guard', label: 'ship-guard', needle: '.rsc/ship-guard.', injects: null },
+  { id: 'danger-guard', label: 'danger-guard', needle: '.rsc/danger-guard.', injects: null },
+  { id: 'gitmoji-guard', label: 'gitmoji-guard', needle: '.rsc/gitmoji-guard.', injects: null },
+  // The bash-era form, still retired by unwireHook. If uninstall knows how to remove it, the report
+  // has to know how to count it.
+  { id: 'legacy-cat-form', label: 'legacy suggest hook', needle: 'skills/rsc/suggest', injects: 'sessionStart' },
+];
+
+// Separators come from whatever platform installed: JSON escapes a Windows backslash as a pair, so
+// the haystack is normalized before comparing. Same lesson as targets/claude.js, same one-liner.
+const entryWiring = (entry) => JSON.stringify(entry).replace(/\\\\/g, '/');
+
+/**
+ * How many times each rsc hook is wired, per event.
+ * @returns {{perEvent: Object<string, Object<string, number>>, indeterminate: string[]}}
+ */
+export function countHookEntries(settings) {
+  const perEvent = {};
+  const indeterminate = [];
+  const hooks = settings && typeof settings === 'object' ? settings.hooks : null;
+  if (!hooks || typeof hooks !== 'object') return { perEvent, indeterminate };
+
+  for (const [event, entries] of Object.entries(hooks)) {
+    // A hand-edited file can put anything here. An event we cannot read is REPORTED, never counted as
+    // zero — a silent zero is exactly the "all clear" this whole delivery exists to stop.
+    if (!Array.isArray(entries)) { indeterminate.push(event); continue; }
+    for (const entry of entries) {
+      const wiring = entryWiring(entry);
+      for (const hook of RSC_HOOKS) {
+        if (!wiring.includes(hook.needle)) continue;
+        perEvent[event] ||= {};
+        perEvent[event][hook.id] = (perEvent[event][hook.id] || 0) + 1;
+      }
+    }
+  }
+  return { perEvent, indeterminate };
+}
+
+// The most copies any one hook has, per injection channel — that is the multiplier that channel pays.
+function maxCopies(perEvent, channel) {
+  let most = 1;
+  for (const byHook of Object.values(perEvent)) {
+    for (const [id, n] of Object.entries(byHook)) {
+      const hook = RSC_HOOKS.find((h) => h.id === id);
+      if (hook && hook.injects === channel && n > most) most = n;
+    }
+  }
+  return most;
+}
+
 function readScope(scopeRoot, label) {
   const settingsPath = join(scopeRoot, '.claude', 'settings.json');
   if (!existsSync(settingsPath)) {
     return { label, root: scopeRoot, wired: false, status: 'ok', alwaysOnBytes: 0, perTurnBytes: 0, version: null };
   }
   let raw;
+  let settings;
   try {
     raw = readFileSync(settingsPath, 'utf8');
-    JSON.parse(raw); // a scope we cannot parse is reported, not guessed at
+    settings = JSON.parse(raw); // a scope we cannot parse is reported, not guessed at
   } catch {
     return { label, root: scopeRoot, wired: true, status: 'unknown', alwaysOnBytes: 0, perTurnBytes: 0, version: null };
   }
   const wired = raw.includes('.rsc/') || raw.includes('.rsc\\\\');
   let version = null;
   try { version = readFileSync(join(scopeRoot, '.rsc', '.version'), 'utf8').trim() || null; } catch { /* unknown */ }
+
+  const { perEvent, indeterminate } = countHookEntries(settings);
+  // The context regime is a STATIC fact, not a caveat: the repeated body is suppressed because the
+  // hook calls the single-shot guard, and that guard is a file on disk. Present → the body lands once
+  // however many entries fire. Absent (an install older than the guard) → every entry injects.
+  //
+  // Measured during clarify: four entries sharing a session_id cost ~1.27× context, not 4×. A figure
+  // that multiplied unconditionally would be the same lie that started this spec, aimed the other way.
+  const dedupeGuard = existsSync(join(scopeRoot, '.rsc', 'hook-once.mjs'));
+  const bodyCopies = dedupeGuard ? 1 : maxCopies(perEvent, 'sessionStart');
+  const gateCopies = dedupeGuard ? 1 : maxCopies(perEvent, 'perTurn');
+
   return {
     label,
     root: scopeRoot,
     wired,
     status: 'ok',
     version,
-    alwaysOnBytes: wired ? alwaysOnBytesFor(scopeRoot, raw) : 0,
-    perTurnBytes: wired && raw.includes('userprompt-gate') ? Buffer.byteLength(SDD_GATE_TEXT) : 0,
+    hookCounts: perEvent,
+    hookCountsUnknown: indeterminate.length ? indeterminate : null,
+    dedupeGuard,
+    alwaysOnBytes: wired ? alwaysOnBytesFor(scopeRoot, raw) * bodyCopies : 0,
+    perTurnBytes: wired && raw.includes('userprompt-gate') ? Buffer.byteLength(SDD_GATE_TEXT) * gateCopies : 0,
   };
 }
 
+// One finding per scope that has any hook wired more than once. Both costs are named, because they
+// are different quantities: processes are 4× unconditionally, bytes only when the guard is missing.
+function duplicateEntryFindings(scopes) {
+  const out = [];
+  for (const scope of scopes) {
+    if (scope.status !== 'ok' || !scope.hookCounts) continue;
+    const repeated = [];
+    for (const [event, byHook] of Object.entries(scope.hookCounts)) {
+      for (const [id, n] of Object.entries(byHook)) {
+        if (n > 1) repeated.push({ event, id, n, label: RSC_HOOKS.find((h) => h.id === id)?.label || id });
+      }
+    }
+    if (!repeated.length) continue;
+    const worst = Math.max(...repeated.map((r) => r.n));
+    const list = repeated.map((r) => `${r.event}/${r.label} ×${r.n}`).join(', ');
+    const contextNote = scope.dedupeGuard
+      ? 'Context cost stays near 1× — the single-shot guard suppresses the repeated always-on body '
+        + '(the residue is the banners printed outside it).'
+      : `Context cost is the full ${worst}× — this scope has no single-shot guard materialized, so every `
+        + 'entry injects the always-on body again.';
+    out.push({
+      id: 'duplicate-hook-entries',
+      severity: 'high',
+      summary: `The ${scope.label} scope wires the same hook more than once: ${list}. `
+        + `Execution cost is ${worst}× processes per event — every session start, every turn, and every `
+        + `Bash command spawns that many. ${contextNote}`,
+      action: 'Re-run an install or sync with a current rsc (`npx @ericrisco/rsc@latest`); one pass '
+        + 'collapses the extra copies. No need to hand-edit settings.json.',
+    });
+  }
+  return out;
+}
+
 // Frontmatter `description` of an installed skill — the part of a skill that is ALWAYS in
 // context, whether or not the skill is ever invoked. Cheap to parse, and the figure that
 // matters most as the catalog grows.
@@ -165,7 +275,18 @@ export function contextBudget({ target, home = homedir(), cwd = process.cwd() }
         + 'root, or update both to a version that de-duplicates at runtime.',
     });
   }
+  findings.push(...duplicateEntryFindings(scopes));
   for (const s of scopes) {
+    if (s.hookCountsUnknown) {
+      findings.push({
+        id: 'indeterminate-hook-event',
+        severity: 'low',
+        summary: `In the ${s.label} scope, ${s.hookCountsUnknown.join(', ')} is not a list of hook entries, `
+          + 'so its copies cannot be counted. A count this report cannot make is said out loud, never '
+          + 'reported as zero.',
+        action: 'Fix that entry in settings.json (or remove it), then re-run `rsc doctor`.',
+      });
+    }
     if (s.status === 'unknown') {
       findings.push({
         id: 'unreadable-scope',

package/scripts/lib/domains.js

@@ -25,7 +25,7 @@ export const DOMAINS = [
   { title: 'Ship & operate — devops', ids: ['docker', 'github-actions', 'git-workflow', 'domains-dns', 'monitoring', 'email-deliverability', 'scaling', 'deployment', 'deprecation'] },
   { title: 'Ship & operate — quality & security', ids: ['code-review', 'security-scan', 'secure-coding', 'testing-py', 'testing-web', 'testing-go', 'e2e-testing', 'accessibility', 'performance', 'error-handling', 'observability'] },
   { title: 'Motion & interface craft', ids: ['design-eng', 'animate', 'animate-expo', 'review-animations', 'improve-animations', 'find-animation-opportunities', 'animation-vocabulary', 'apple-design', 'prototype'] },
-  { title: 'Design & content craft', ids: ['design', 'presentations', 'course-storytelling', 'course-builder', 'technical-writing', 'translation-l10n'] },
+  { title: 'Design & content craft', ids: ['design-loop', 'design', 'design-dna', 'presentations', 'course-storytelling', 'course-builder', 'technical-writing', 'translation-l10n'] },
   { title: 'Knowledge & meta', ids: ['knowledge-ops', 'codebase-onboarding', 'research-ops', 'decision-records', 'continuous-learning', 'skill-scout', 'context-budget', 'roast-me', 'fable-operator'] },
 ];
 

package/scripts/lib/recommend.js

@@ -11,6 +11,8 @@ const OUTCOMES = {
   go: 'Your Go backend service',
   postgresdb: 'Store your data reliably',
   design: 'Make it look good and convert',
+  'design-loop': 'Make it as good as the site you admire',
+  'design-dna': 'Keep every page looking like yours',
   marketing: 'Copy that sells',
   presentations: 'On-brand presentations',
   'course-storytelling': 'Teach so it actually lands',

package/scripts/rsc.js

@@ -144,6 +144,11 @@ function printContextBudget(b) {
   }
   for (const s of b.scopes.filter((x) => x.wired)) {
     say(`  Scope ${s.label.padEnd(8)}: ${s.root}${s.version ? ` (${s.version})` : ''}${s.status === 'unknown' ? ' — UNREADABLE' : ''}`);
+    // Copies are printed only when there is something to see. A line saying "×1" on every healthy
+    // box is noise, and noise is what gets a report skimmed instead of read.
+    const repeated = Object.entries(s.hookCounts || {})
+      .flatMap(([event, byHook]) => Object.entries(byHook).filter(([, n]) => n > 1).map(([id, n]) => `${event}/${id} ×${n}`));
+    if (repeated.length) say(`  Hook copies     : ${repeated.join(' · ')}`);
   }
   for (const f of b.findings) {
     say(`\n  [${f.severity.toUpperCase()}] ${f.summary}`);

package/skills/design/SKILL.md

@@ -2,7 +2,7 @@
 name: design
 description: "Use when designing or refreshing a web UI or landing page — visual concept, type/color/spacing/motion tokens, composition, rescuing a UI that reads AI-generic, or a graded design review. Brand-grounded and research-first; ships Tailwind v4 + Next.js 15 under WCAG 2.2 AA and Core Web Vitals budgets. NOT the words on the page (that is `marketing`), NOT the App Router build (that is `nextjs`)."
 tags: [design, ux, ui, landing, conversion]
-recommends: [nextjs, marketing]
+recommends: [design-loop, design-dna, nextjs, marketing]
 origin: risco
 ---
 

package/skills/design-dna/PROMPT.md

@@ -0,0 +1,211 @@
+<!-- design-dna: the standalone prompt.
+     Paste into any session and attach the winning design. Nothing else is needed.
+     Kept verbatim from the source method; edit only if you also edit ../SKILL.md. -->
+
+You are a design forensics analyst. I am going to give you one design I love.
+
+Your job is not to praise it, describe it, or make something like it. Your job is
+to CODIFY it: reduce it to the smallest set of rules that will reproduce its
+identity on completely different content, forever, across any medium.
+
+The output is a reusable skill. Treat the design in front of you as evidence,
+not as a brief.
+
+## THE STANDARD YOU ARE HELD TO
+
+A specification that cannot fail is not a specification.
+
+If every rule you write is one a bad output could still satisfy, you have written
+a mood board. Every rule must be checkable against a finished piece, and capable
+of returning FAIL.
+
+## WHAT ACTUALLY CARRIES A DESIGN'S IDENTITY
+
+Read this before you start. Getting it wrong is the standard failure.
+
+1. RELATIONSHIPS, NOT VALUES. "The headline is 96px" is nearly worthless. "The
+ headline is 8x the body, never under 6x" is the identity. Style lives in the
+ ratios between elements. A list of measurements is exactly that information
+ thrown away.
+2. PROPORTIONS OF COLOUR, NOT JUST COLOUR. The same three hex codes at 60/30/10
+ and at 90/8/2 are two unrelated designs. Always record coverage.
+3. ONE BREAK IN THE SYSTEM. Almost every design worth copying has exactly one
+ deliberate exception: type crossing an image, a rule overshooting its margin,
+ a numeral clipped by the canvas edge. It is the highest-information element
+ present and the first thing a mechanical extraction loses, because extraction
+ looks for systems and this is a break from the system. Find it. Name it.
+4. REFUSALS, NOT JUST PERMISSIONS. Listing six colours tells a model it may use
+ six. If the reference uses one accent on 3% of the canvas, the design's real
+ content is a refusal. Write the refusals down.
+5. ABSENCE IS DESIGN. No shadows. No icons. No curves. Nothing centred. Record
+ what is missing with the same care as what is present.
+6. STRUCTURE, NOT ONLY STYLING. If a style has no named layouts, output #8 will
+ not sit beside output #1 as a set. You get consistent styling and
+ inconsistent structure, which reads as sloppiness.
+
+## RUN THIS IN SEVEN STEPS. SHOW YOUR WORK AT EACH.
+
+### STEP 1 - OBSERVE. Do not interpret.
+
+Produce a flat inventory of literal observations. Measure, do not describe.
+
+Sample real colours. Estimate what share of the canvas each covers. Count the
+type sizes, the weights, the accent uses. Measure the ratio between largest and
+smallest type. Note margins as a percentage of the canvas, not in pixels. Record
+texture, grain, edges, image treatment. Write down what is absent.
+
+No judgements yet. Interpretation here is how you end up specifying a design
+that is not the one in front of you.
+
+### STEP 2 - DEBATE IT WITH YOURSELF. Two loops, honestly opposed.
+
+LOOP A, THE MAXIMALIST. Argue: anything not written down will be improvised, and
+improvisation is where consistency dies. List every property exhaustively.
+Miss nothing.
+
+LOOP B, THE MINIMALIST. Argue: a copy can match every value and still look
+generic. Identity lives in a handful of moves and a wall of refusals. Name the
+3-9 moves that actually carry it, and the bans that keep output off the average.
+Attack Loop A's list. Say which entries are load-bearing and which are trivia.
+
+ADJUDICATE. For every property, ask:
+
+ If I changed this value, would the output stop looking like the reference?
+
+Yes, it is load-bearing. No, it is trivia, and trivia dilutes attention.
+
+Then resolve the debate the right way, which is NOT a compromise. Both sides are
+correct about different documents:
+
+- The EXHAUSTIVE record is for me and for build tools. Any size, because a
+ compiler does not sample.
+- The PROMPT PAYLOAD is for a model with a finite attention budget. Hard cap:
+ 2KB of text. Compliance drops as rules pile up, and material in the middle of
+ a long document gets recovered far worse than material at either end.
+
+### STEP 3 - CODIFY. Write dna.json.
+
+Fill these keys. Omit any that genuinely do not apply.
+
+meta name, slug, source files, date, medium of origin,
+ not_copied (any real logo, wordmark or licensed image -
+ reproduce the SYSTEM, never the MARKS)
+soul one_line (max 160 chars, concrete nouns, no marketing words),
+ 3-5 adjectives, lineage (Swiss editorial / 90s flyer / brutalist),
+ read_distance (thumb | arms-length | desk | room | street),
+ energy: density, variance, contrast, warmth - each 1-10
+palette colors[]: role, hex, descriptive name ("dusty plum", never
+ "accent-500" - image and video models cannot read token names)
+ coverage: percentage of canvas per role, summing to ~100
+ banned: colour behaviours forbidden
+type families[]: role, family, REQUIRED fallback, weights, licence risk
+ scale: display_to_body_ratio (the typographic signature),
+ steps, max_sizes_per_frame
+ treatment: tracking, leading, case, measure, numerals
+space grid, margin_pct, gutter_pct, alignment, rhythm,
+ negative_space (where the emptiness is and how big),
+ safe_area per platform
+ USE PERCENTAGES so one spec drives a 1080x1350 carousel and a
+ 1920x1080 slide without a rewrite
+surface texture (kind, opacity, scale, stacking order), edges, elevation,
+ imagery treatment, iconography
+signatures[] 3-9. move (name it like a technique), how (AS A RATIO OR
+ RELATIONSHIP), when it appears, never (how it gets used wrong)
+weird_move the single break in the system. Its own key, deliberately.
+archetypes[] named layouts: id, purpose in a sequence, anatomy, content budget
+motion easing curves, durations, entrances, what NEVER moves,
+ reduced-motion fallback. Omit for static work.
+voice register, sentence length, headline shape, banned words.
+ Copy is part of the design.
+bans[] minimum 5, written as absolutes
+tests[] minimum 8. See Step 4.
+
+### STEP 4 - WRITE TESTS THAT CAN FAIL. Eight to twelve.
+
+Binary and measurable:
+
+- "Accent colour covers under 8% of the canvas."
+- "No more than 3 type sizes in a single frame."
+- "Largest-to-smallest type ratio is above 6:1."
+- "Smallest type is at least 28px at 1080px canvas width."
+- "The weird move is present, exactly once."
+- "Body copy stays under 65 characters per line."
+- "Squint from three metres. Does the mass distribution match the reference?"
+
+Not tests: "feels premium", "looks clean". If two people could disagree about
+the answer, it is not a test. Mark which ones a script could decide.
+
+### STEP 5 - RECONSTRUCT AND DIFF. Do not skip this.
+
+Rebuild the original reference using only dna.json. Close the reference. Work
+from the spec alone.
+
+Put your rebuild beside the original. List every single difference.
+
+Every difference is a field the spec forgot. Fold each one back in. Record what
+was missing. Go again. Repeat until a stranger could not pick the copy from the
+original.
+
+This is the only honest test of completeness that exists. A spec that has never
+been used to rebuild its own source has never been tested. Expect two or three
+passes. Expect the gaps to be things you were sure were obvious.
+
+### STEP 6 - EMIT THE SKILL.
+
+Write a folder named after meta.slug:
+
+ <slug>/
+ SKILL.md how to use this style
+ PROMPT.md the 2KB payload. THIS is what goes in a context window.
+ dna.json the full record. NEVER pasted into a prompt.
+ reference/ the original, kept forever
+ example/ one worked output, the canonical proof
+ tools/check.py the automatable tests, exits non-zero on failure
+
+PROMPT.md is the file that matters. Order it exactly like this, because
+attention is strongest at the two ends and weakest in the middle:
+
+ 1. The reference image, attached and named first
+ 2. soul.one_line
+ 3. The weird move, alone, unmissable
+ 4. The 3-9 signature moves, as ratios
+ 5. The bans, as absolutes
+ 6. Palette and type - roles and coverage only, not a full ramp
+ 7. Archetype names and when to use each
+ 8. The self-check, last
+
+Nothing else. If it does not change what the output looks like from three metres
+away, it belongs in dna.json, not here. To add a tenth signature you must delete
+one. The cap is the point: it forces you to decide, and an uncapped spec just
+ships your indecision.
+
+End PROMPT.md with this line:
+
+ Before returning any output, run every test in the self-check. Name each test
+ and its result. If any fails, repair the output and run them again. Never
+ return output with a failing test and a note explaining it away.
+
+### STEP 7 - TELL ME WHAT YOU ARE UNSURE ABOUT.
+
+List every value you inferred rather than measured, and every rule you are under
+70% confident in. These are where the style will drift first, and I would rather
+know now.
+
+## RULES FOR YOU, THE ANALYST
+
+- Never invent a value you could measure. If you cannot measure it, say so and
+ mark it inferred.
+- Never copy a real logo, wordmark, licensed photograph or proprietary typeface.
+ Put them in meta.not_copied and substitute. Reproduce the system, never the
+ marks.
+- Descriptive colour names, not systematic ones. "Dusty plum" travels to an
+ image model. "accent-500" does not.
+- Every font family needs a fallback. Silent Arial substitution is the most
+ common way a reproduction dies quietly.
+- When you are tempted to add a rule because output looks generic, add a ban
+ instead. A prohibition steers harder than a permission, and one ban can rule
+ out an entire space in a single line.
+- One skill per style. Never merge two identities into one spec. The average of
+ two good designs is a bad design.
+
+Begin at Step 1. Show your work.

package/skills/design-dna/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: design-dna
+description: "Use when a design has won and its look must survive: codify it into a permanent style skill with measured ratios, bans and tests that can fail, then build new pieces in that exact look. Fires on 'turn this into a skill', 'keep the same style', 'my output drifted'. NOT finding the winner (that is `design-loop`), NOT the words (that is `marketing`)."
+tags: [design, style, dna, codify, skill-factory, consistency]
+recommends: [design-loop, design, nextjs, marketing]
+origin: risco
+---
+
+# Design DNA - one beautiful design into a permanent skill
+
+*A design loop finds you one beautiful thing. This turns that one thing into a skill you keep forever, so you can make more of it, in any format, without the look drifting.*
+
+**Not only about "designs".** The subject is anything that got built: a website, a landing page, a poster, a motion graphic, a carousel, a deck. Same system, same file, same tests. The format is an output, not the subject.
+
+## The problem this solves
+
+Nobody wrote down **why** the winner was beautiful. Next time you ask for "the same style" you get something close, then something a bit off, then something generic. Every rule you do not write down, the model has to guess, and it does not guess randomly: it guesses the average of everything it has ever seen. That average is what people call slop. Slop is the sound of an unwritten rule.
+
+## Two modes
+
+| You say | Mode | What happens |
+|---|---|---|
+| "codify this", "turn this into a skill", here is the winner | **CAPTURE** | Run the seven steps below. Output: a new style skill folder. |
+| "build X in <style>", "another one like the last", `/<slug>` | **REUSE** | Load that style's `PROMPT.md` only, build, then run its self-check before returning. |
+
+If a `dna.json` already exists for the style named, you are in REUSE. Never re-derive a style that has a record.
+
+## Hard rules (these are the skill)
+
+1. **A specification that cannot fail is not a specification.** If every rule you wrote is one a bad output could still satisfy, you wrote a mood board.
+2. **Compile, do not paste.** Two files, always. `dna.json` is the record, any size, and it **never** enters a prompt. `PROMPT.md` is the payload, **hard cap 2KB**, and it is the only thing that does.
+3. **Always attach the reference image.** Highest-leverage move available and close to free: image conditioning runs on its own pathway, so it does not eat the attention your words are competing for.
+4. **Ratios, not values.** "The headline is 96px" is nearly worthless. "The headline is 8x the body, never under 6x" is the identity.
+5. **Coverage, not just colour.** The same three hex codes at 60/30/10 and at 90/8/2 are two unrelated designs.
+6. **Percentages, not pixels,** in everything spatial. One spec has to drive a 1080x1350 carousel and a 1920x1080 slide with no rewrite.
+7. **When output looks generic, add a ban, not a rule.** A positive instruction is one weak vote against a landslide; "never centre the hero" deletes the landslide from the options. Bans should outnumber positive style rules.
+8. **One skill per style.** Never merge two identities into one spec. The average of two good designs is a bad design.
+9. **Reproduce the system, never the marks.** Real logos, wordmarks, licensed photographs and proprietary typefaces go in `meta.not_copied` with a named substitute.
+10. **Step 5 is not optional.** A spec that has never been used to rebuild its own source has never been tested.
+
+## CAPTURE - the seven steps
+
+Run `PROMPT.md` as written. It is the operative artefact and it is self-contained; this section is the map, not a second copy of it.
+
+| Step | Name | Non-negotiable output |
+|---|---|---|
+| 1 | **Observe** | Flat inventory of literal measurements. Sampled hexes, coverage estimates, type counts, largest-to-smallest ratio, margins as percentages, texture, and **what is absent**. No judgements: interpreting here is how you end up specifying a design that is not the one in front of you. |
+| 2 | **Debate** | Loop A argues exhaustive, Loop B argues nine moves and a wall of refusals, then adjudicate each property with one question: *if I changed this value, would it stop looking like the reference?* Yes is load-bearing, no is trivia, and trivia dilutes attention. Resolve it by splitting documents, not by compromising. |
+| 3 | **Codify** | `dna.json` against `design-dna.schema.json`. Descriptive colour names ("dusty plum", never "accent-500": image and video models cannot read token names). Every family gets a fallback. |
+| 4 | **Tests that can fail** | 8 to 12, binary and measurable, each marked auto or human. |
+| 5 | **Reconstruct and diff** | Close the reference. Rebuild it from `dna.json` alone. Put them side by side and list **every** difference: each one is a field the spec forgot. Fold them in, record them in `reconstruction.gaps_found`, go again. Expect two or three passes, and expect the gaps to be things you were sure were obvious. |
+| 6 | **Emit the skill** | The folder below. |
+| 7 | **Declare uncertainty** | Every value inferred rather than measured, and every rule under 70% confidence, into `meta.confidence_notes`. That is where the style drifts first. |
+
+### What gets emitted
+
+    ~/.claude/skills/<slug>/
+      SKILL.md          how to use this style, and when not to
+      PROMPT.md         the 2KB payload. THIS is what enters a context window
+      dna.json          the full record. NEVER pasted into a prompt
+      design-dna.schema.json -> validated against the parent copy
+      reference/        the original, kept forever
+      example/          one worked output, the canonical proof
+      scripts/check.py  the auto tests, exits non-zero on failure
+
+Scaffold from `templates/` and validate before you claim it works:
+
+    python3 ~/.claude/skills/design-dna/scripts/emit.py <slug>            # scaffold + validate
+    python3 ~/.claude/skills/<slug>/scripts/check.py <output-file>        # run the auto tests
+
+### PROMPT.md ordering is fixed
+
+Attention is strongest at the two ends and weakest in the middle, so the order is a mechanism, not a style choice:
+
+1. The reference image, attached and named first
+2. `soul.one_line`
+3. The weird move, alone, unmissable
+4. The 3-9 signature moves, as ratios
+5. The bans, as absolutes
+6. Palette and type: roles and coverage only, never a full ramp
+7. Archetype names and when to use each
+8. The self-check, last
+
+Nothing else. If it does not change what the output looks like from three metres away, it belongs in `dna.json`. To add a tenth signature you must delete one.
+
+Last line of every `PROMPT.md`, verbatim:
+
+> Before returning any output, run every test in the self-check. Name each test and its result. If any fails, repair the output and run them again. Never return output with a failing test and a note explaining it away.
+
+## REUSE - building with a captured style
+
+1. Load **only** that style's `PROMPT.md`. Attach `reference/`. Do not read `dna.json` into context; read it only to answer a specific measured question or to regenerate the payload.
+2. Pick an archetype by name before writing anything. Structure first: unnamed layouts are why piece 8 does not sit beside piece 1 as a set.
+3. Build. For web, hand the build to `../nextjs/SKILL.md` and the words to `../marketing/SKILL.md`; the identity stays here.
+4. Run the self-check, name each test and its result, repair and re-run on any failure.
+5. If output drifts, do not add a rule. Consult the table below.
+
+## When it goes wrong
+
+| What you see | Cause | Fix |
+|---|---|---|
+| Matches every value, still looks generic | Signature moves missing, or too many | Cut to 3-9, rewrite each as a ratio |
+| Drifts back to the stock AI look | Not enough bans | Bans should outnumber positive style rules |
+| Piece 1 and piece 8 do not match | No named layouts | Add archetypes |
+| The accent reads as a theme, not an accent | No coverage percentages | Add them |
+| Works on a slide, breaks on a carousel | Pixel values in the spacing | Convert to percentages |
+| Obeys some rules, ignores others, differently each run | Payload over the cap | Cut to 2KB |
+| Your best rule keeps getting ignored | It is buried in the middle | Move it to the top or the bottom |
+| Fine, but forgettable | No weird move | Find the one break in the system |
+| Spec feels complete, output is wrong | You skipped Step 5 | Rebuild the original from the spec. Compare. |
+
+## Styles captured so far
+
+| Style | Reads as | Weird move |
+|---|---|---|
+| `../cold-press/SKILL.md` | newsprint editorial, serif at 8x, one vermilion | section numeral clipped by the right edge |
+| `../night-shift/SKILL.md` | near-black instrument panel, one phosphor green | status ribbon severed mid-word by the right edge |
+| `../soft-optics/SKILL.md` | warm paper, lowercase display at 6x, one olive | display line crossing a tinted plate's bottom edge |
+
+Each is a finished skill: reference, `dna.json`, a capped payload, a worked proof, and tests that exit non-zero. Never merge two of them: the average of two good designs is a bad design.
+
+## Hand-offs
+
+- **No winner yet, no reference to measure** -> `../design-loop/SKILL.md` first: it takes a real reference and converges on a piece that beats it. Come back with the winner. Capturing an average of several candidates produces the average, which is the thing you are trying to escape.
+- **The words on the page** -> `../marketing/SKILL.md`. `voice` in `dna.json` constrains them; it does not write them.
+- **The build** -> `../nextjs/SKILL.md` (App Router, React 19) or `../react/SKILL.md` (Vite SPA).
+- **SDD gate.** Capturing a style writes a skill, not product code, so it needs no spec. The moment its output becomes a new feature or a non-trivial behaviour change in a real app, `../specify/SKILL.md` runs first.
+
+## Files
+
+| File | What it is |
+|---|---|
+| `PROMPT.md` | The standalone prompt. Paste anywhere, attach the design, done. |
+| `design-dna.schema.json` | Every field of `dna.json`, explained. |
+| `scripts/emit.py` | Scaffolds and validates an emitted style skill. |
+| `templates/` | `SKILL.md`, `PROMPT.md` and `check.py` skeletons for the emitted skill. |
+| `references/method.md` | The full method and the research each decision traces to. Read once, not per run. |
+
+**Why any of this works** is not opinion: lost-in-the-middle recovery, instruction-compliance decay under constraint count, style being formally the correlation between features rather than the features, and decoupled image cross-attention. The citations are in `references/method.md`.