feat(skills): add aidd-genesplice evolutionary optimization skill

ai/skills/aidd-genesplice/README.md

@@ -0,0 +1,43 @@
+# aidd-genesplice
+
+Evolutionary optimization framework for creative output — copy, UI prototypes,
+pitches, strategies, or any artifact where multiple viable approaches exist
+and you need to find the optimal blend.
+
+## Why
+
+Generating a single "best attempt" leaves value on the table. Genesplice
+borrows from genetic algorithms: competing candidates with distinct gene
+profiles are scored against researched criteria, and the strongest traits are
+spliced across generations. Mutations introduce structural novelty that no
+single-pass approach would discover. The result compounds improvements across
+generations — the winner rarely looks like any single parent.
+
+## Commands
+
+```
+/genesplice [artifact]
+```
+
+Run the full evolutionary optimization pipeline: research criteria → generate
+candidates → score → splice → mutate → repeat → pick winner.
+
+```
+/genesplice score [candidates]
+```
+
+Score existing candidates against the researched criteria without running a
+new generation.
+
+```
+/genesplice splice [candidate-a] [candidate-b]
+```
+
+Manually splice two specific candidates, combining their best genes into a
+new candidate.
+
+## When to Use
+
+- Optimizing creative output (pitches, copy, UI designs, strategies)
+- When "good enough" isn't enough — need a provably best version
+- When there are multiple viable approaches and you need the optimal blend

ai/skills/aidd-genesplice/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: aidd-genesplice
+description: >
+  Evolutionary optimization framework for creative output.
+  Research criteria, generate competing candidates, score, splice best genes,
+  mutate, repeat. Use when optimizing copy, UI prototypes, pitches, strategies,
+  or any artifact where "good enough" isn't enough.
+---
+
+# Evolutionary Optimizer
+
+Act as an evolutionary optimization engine. Generate competing candidates
+with distinct gene profiles, score them against researched criteria, splice
+the best traits across generations, and introduce mutations until scores
+plateau.
+
+Competencies {
+  domain research and criteria synthesis
+  divergent candidate generation
+  structured scoring and comparison
+  gene splicing (recombination of best traits)
+  mutation (structurally novel ideas)
+}
+
+## Process
+
+```
+genesplice(context, n=2) {
+  gatherContext(context)     // effect
+    |> research              // effect → thinking
+    |> runGenerations(n)     // effect → thinking, ×n
+    |> summarize             // thinking
+}
+```
+
+## Step 1 — Gather Context
+
+gatherContext(userPrompt) => enrichedContext {  // effect
+  1. Scan workspace for existing artifacts relevant to the prompt
+     (prior candidates, specs, related files) — pull them into context
+  2. Extract any fitness criteria the user included in their prompt
+}
+
+## Step 2 — Research
+
+Isolated sub-stages so reasoning and I/O effects can be tested independently.
+
+fetchBestPractices(enrichedContext) => rawFindings {  // effect
+  (enrichedContext has sufficient criteria) => skip; pass existing criteria as rawFindings
+  (no criteria) =>
+    Use web search to find best practices for this class of artifact.
+    Favor research papers, peer-reviewed studies, and authoritative industry
+    findings over opinion pieces or blog posts.
+}
+
+synthesizeCriteria(rawFindings, enrichedContext) => criteria {  // thinking
+  1. Lock in any user-supplied criteria from enrichedContext first — not overridable
+  2. Synthesize researched findings into additional scored criteria (0–10 each)
+     that fill gaps — one criterion per finding, no bundling
+  3. Cite every researched criterion (author, title, URL or DOI) — reject uncitable criteria
+  4. Always include (no citation needed):
+     - *Information Efficiency* — does every element add NEW information?
+     - *Narrative Structure* — does the reading order tell a story?
+  5. For UI prototypes: add "A11y/Readability" (weighted ×2)
+
+  output format:
+    ## [Criterion Name] (weight: N)
+    [One paragraph grounded in the research.]
+    *Sources:* [Author, "Title", URL or DOI]
+}
+
+## Step 3 — Run Generations
+
+Repeat n times. Each round produces 2 candidates and a splice seed for the next round.
+
+buildCandidates(seed, context) => candidates {  // effect
+  1. Generate 2 candidates with *distinct gene profiles* from the seed — not minor variations
+  2. Save each to the prototypes folder (see references/candidate-output.md)
+  3. For UI candidates: run quality gate (see references/quality-gate.md)
+}
+
+scoreAndSplice(candidates, criteria) => nextSeed {  // thinking
+  1. Score each candidate against all criteria
+  2. List pros and cons for each
+  3. Identify best genes from each candidate
+  4. Splice best genes into next generation seed
+  5. Introduce 1 mutation (structurally novel idea) into the seed
+}
+
+## Step 4 — Summarize
+
+scoreAllCandidates(generations[]) => scoringTable {  // thinking
+  1. Final scoring table across all criteria for every candidate from every generation
+  2. Stack rank all candidates
+
+  scoringTable format:
+    Criteria            Cand A    Cand B    Cand C  ...
+    ────────────────    ──────    ──────    ──────
+    [Criterion 1]         ?         ?         ?
+    [Criterion 2]         ?         ?         ?
+    ...
+    TOTAL                ??        ??        ??
+}
+
+suggestWinner(scoringTable) => winner {  // thinking
+  1. Name the winner
+  2. Show which genes it inherited and from whom
+  3. State the "one core idea" the output delivers
+  4. Justify selection against the *purpose* of the artifact
+     (e.g. "get a meeting" not "look impressive")
+}
+
+Constraints {
+  Each candidate must have a *distinct gene profile* — not minor variations.
+  Mutations introduce structural novelty (e.g. "what if we flip the entire approach?").
+  Best genes can come from the lowest-scoring candidate.
+  Always show the scoring table — transparency builds trust.
+  Don't score your own work without a holistic "does this actually work?" gut check.
+  A collection of individually optimized genes can produce a weaker organism
+  than a coherent but less flashy design. The final splice needs holistic review.
+  All candidates from all generations are preserved — never delete earlier gens.
+  Run autonomously by default — no mandatory user review steps.
+}
+
+Commands {
+  🧬 /genesplice [-n=2] [context] — run full evolutionary optimization; n = number of generations
+  /genesplice research [context] — gatherContext + research only; output criteria
+  /genesplice score [candidates] — score existing candidates against criteria
+  /genesplice splice [candidate-a] [candidate-b] — manually splice two candidates
+}

ai/skills/aidd-genesplice/references/candidate-output.md

@@ -0,0 +1,14 @@
+# Candidate Output
+
+Every candidate is saved to a folder inside the designated prototypes folder.
+
+cuid2Slug = ${npx @paralleldrive/cuid2 --slug}
+
+```
+prototypes/$artifactName/gen${n}-${semanticLabel}${cuid2slug}/
+├── $artifactName    # The candidate itself
+├── preview.png      # Screenshot for quick comparison
+└── full.png         # Full-page screenshot
+```
+
+Generate screenshots when relevant, e.g. candidate has a UI.

ai/skills/aidd-genesplice/references/learnings.md

@@ -0,0 +1,32 @@
+# Learnings
+
+## Generation Size
+
+2 candidates per generation is the sweet spot — enough diversity, manageable scope.
+
+## Mutations Win
+
+Mutations (structurally novel ideas) often contribute the strongest genes.
+The winning candidate rarely looks like any single parent — it's the splice
+that wins.
+
+## Always Preview
+
+Always render/preview each candidate before scoring — catch layout issues early.
+
+## Emergent Redundancy Problem (Critical)
+
+Scoring individual criteria can miss problems that only emerge in the
+*combination*. Example: giant stats (scored 9 on Typography) + italic
+punchline (scored 9 on Copy Punch) = the punchline restated the stats.
+Redundancy that no single criterion caught.
+
+**Must add two holistic criteria to every scoring matrix:**
+
+1. *Information Efficiency* — does every element add NEW information?
+2. *Narrative Structure* — does the reading order tell a story?
+
+**A collection of individually optimized genes can produce a weaker organism
+than a coherent but less flashy design.** Genesplice is good at finding strong
+components, but the final splice needs holistic review against the *purpose*
+of the artifact (e.g. "get a meeting" not "look impressive").

ai/skills/aidd-genesplice/references/quality-gate.md

@@ -0,0 +1,31 @@
+# Quality Gate (Per-Candidate)
+
+For UI prototype candidates, run the automated a11y scorer after generating
+each candidate:
+
+```bash
+bun run aidd-custom/skills/aidd-ui/scripts/a11y-score.ts path/to/candidate/index.html --fix-hints
+```
+
+## Flow
+
+```
+generate → save to prototypes/ → run a11y-score.ts
+  → score ≥ B? → proceed to genesplice scoring
+  → score < B? → /aidd-fix using --fix-hints output → re-score
+  → still < B after 2 fix attempts? → score as-is but flag in scoring table
+```
+
+## A11y Score Mapping
+
+The a11y score maps to genesplice criteria as:
+
+| Grade | Score |
+|-------|-------|
+| A     | 10    |
+| B     | 8     |
+| C     | 5     |
+| D     | 3     |
+| F     | 1     |
+
+This criterion is weighted ×2 in the scoring table.

ai/skills/index.md

@@ -7,6 +7,7 @@
 - aidd-error-causes - Use the error-causes library for structured error handling in JavaScript/TypeScript. Use when throwing errors, catching errors, defining error types, or implementing error routing.
 - aidd-fix - Fix a bug or implement review feedback following the AIDD fix process. Use when a bug has been reported, a failing test needs investigation, or a code review has returned feedback that requires a code change.
 - aidd-functional-requirements - Write functional requirements for a user story. Use when drafting requirements, specifying user stories, or when the user asks for functional specs.
+- aidd-genesplice - Evolutionary optimization framework. Research criteria → generate N candidates → score pros/cons → splice best genes → repeat generations → score all → pick winner with justification. Use when optimizing any creative output (copy, design, strategy, pitches).
 - aidd-javascript - JavaScript and TypeScript best practices and guidance. Use when writing, reviewing, or refactoring JavaScript or TypeScript code.
 - aidd-javascript-io-effects - Isolate network I/O and side effects using the saga pattern with call and put. Use when making network requests, invoking side effects, or implementing Redux sagas.
 - aidd-jwt-security - JWT security review patterns. Use when reviewing or implementing authentication code, token handling, session management, or when JWT is mentioned.