Add /genesplice to AIDD Framework

[ericelliott]

Add /genesplice Evolutionary Optimization Skill

Summary

Add the /genesplice skill to the aidd framework — an evolutionary optimization algorithm for creative output. It works by generating competing candidates with distinct "gene profiles," scoring them against researched criteria, splicing the best traits, and introducing mutations across generations until scores plateau.

Please use the /aidd-upskill skill in the claude/fix-issue-93-6x2Oq branch to review the skill. Make sure it has adequate documentation, tools, tests, etc.

When to Use

• Optimizing creative output (pitches, copy, UI designs, strategies)
• When "good enough" isn't enough — need a provably best version
• When multiple viable approaches exist and you need the optimal blend

How It Works

ResearchCriteria → Generate N candidates → Score pros/cons → Splice best genes → Mutate → Repeat → Score all → Pick winner with justification

File Structure

skills/genesplice/
└── SKILL.md

Source Code

skills/genesplice/SKILL.md

---
name: genesplice
description: "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)."
---

# /genesplice — Evolutionary Optimization

## When to Use
- Optimizing creative output (pitches, copy, designs, strategies)
- When "good enough" isn't enough — need provably best version
- When there are multiple viable approaches and you need to find the optimal blend

## The Algorithm

    ```
1. ResearchCriteria
   - Search for domain-specific best practices
   - Synthesize into scored criteria (0-10 each)
   - Source everything — no unsourced criteria
   - For UI prototypes: always include "A11y/Readability" criterion (weighted ×2)

2. Generation Loop (n=2 per generation):
   a. Build 2 candidates with distinct "gene profiles"
   b. Save each candidate to the prototypes folder (see Candidate Output below)
   c. Run automated review per-candidate (see Quality Gate below)
   d. If review fails: run /aidd-fix → re-review → repeat until pass or 2 attempts
   e. Score each (post-fix) against all criteria
   f. List pros and cons for each
   g. Identify best genes from each candidate
   h. Splice best genes into next generation
   i. Introduce 1 mutation (novel structural idea) per generation
   j. Repeat until scores plateau or time-boxed

3. ScoreAllCandidates
   - Final scoring table across all criteria
   - Stack rank

4. SuggestWinner + JustifySelection
   - Name the winner
   - Show which genes it inherited and from whom
   - State the "one core idea" the output delivers
    ```

## Candidate Output

Every candidate is saved to a real file in the project's prototypes folder. Never keep candidates only in chat.

    ```
projects/{project}/prototypes/{artifact}/gen{N}-{short_id}/
├── index.html       # The candidate itself
├── preview.png      # Screenshot for quick comparison
└── full.png         # Full-page screenshot
    ```

- `{short_id}` = 8-char random alphanumeric, e.g. `gen3-a7k2m9p1`
- Generation number increments across the whole evolutionary run
- All candidates from all generations are preserved (never delete earlier gens)
- `SCORES.md` at the `{artifact}/` level tracks all candidates across generations

## 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 per candidate:
    ```
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
    ```

The a11y score maps to genesplice criteria as:
- A = 10, B = 8, C = 5, D = 3, F = 1
- This criterion is weighted ×2 in the scoring table

## Key Principles
- Each candidate should 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
- Score improvements should compound across generations
- Always show the scoring table — transparency builds trust

## Scoring Template
    ```
Criteria          Cand X    Cand Y
──────────────    ──────    ──────
[Criterion 1]       ?         ?
[Criterion 2]       ?         ?
...
TOTAL              ??        ??
    ```

## Example: Investor One-Pager (April 2026)
- **Gen 1**: Inevitability Machine (73) vs Platform Shift Bet (71)
- **Gen 2**: Narrative Splice (78) vs Numbers-First Mutation (78)
- **Winner**: Final Splice — 85/100 (+12 from Gen 1 average)
- **Key insight**: Giant stat hero (from mutation D) + narrative punchline specificity (from A via C) + loss aversion closer (from B) produced compound improvement no single candidate had

## Learnings
- 2 candidates per generation is the sweet spot — enough diversity, manageable scope
- 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 render/preview each candidate before scoring — catch layout issues early

### Critical: Emergent Redundancy Problem (April 2026)
- 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?
- Don't score your own work. The process needs an external "does this actually work as a whole?" gut check.
- **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").

Implementation Notes

• The skill is a single SKILL.md file — no scripts or references directory needed (yet)
• Code blocks within the file above have been indented by 4 spaces to avoid breaking the outer fence
• The quality gate references an a11y scorer script (aidd-custom/skills/aidd-ui/scripts/a11y-score.ts) — this dependency should be noted but is only relevant for UI prototype candidates
• The scoring template and learnings sections encode hard-won lessons from real usage (April 2026 investor one-pager optimization)

Key Design Decisions

1. 2 candidates per generation — enough diversity without exploding scope
2. Mandatory mutations — structurally novel ideas often contribute the strongest genes
3. Holistic criteria (Information Efficiency + Narrative Structure) — added after discovering that individually optimized genes can produce a weaker combined organism
4. Preserve all generations — never delete earlier candidates; the evolutionary history matters for understanding why the winner works