diff --git a/ai/skills/aidd-genesplice/README.md b/ai/skills/aidd-genesplice/README.md new file mode 100644 index 0000000..ae3cb3d --- /dev/null +++ b/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 diff --git a/ai/skills/aidd-genesplice/SKILL.md b/ai/skills/aidd-genesplice/SKILL.md new file mode 100644 index 0000000..9982b82 --- /dev/null +++ b/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 +} diff --git a/ai/skills/aidd-genesplice/references/candidate-output.md b/ai/skills/aidd-genesplice/references/candidate-output.md new file mode 100644 index 0000000..0defef6 --- /dev/null +++ b/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. diff --git a/ai/skills/aidd-genesplice/references/learnings.md b/ai/skills/aidd-genesplice/references/learnings.md new file mode 100644 index 0000000..32a7e33 --- /dev/null +++ b/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"). diff --git a/ai/skills/aidd-genesplice/references/quality-gate.md b/ai/skills/aidd-genesplice/references/quality-gate.md new file mode 100644 index 0000000..a11189f --- /dev/null +++ b/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. diff --git a/ai/skills/index.md b/ai/skills/index.md index b660419..975df75 100644 --- a/ai/skills/index.md +++ b/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.