# evo-search

Adopt this skill: https://proskills.md/skills/other/smkalami-skills-skills-evo-search

Page: https://proskills.md/skills/other/smkalami-skills-skills-evo-search
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/evo-search/SKILL.md
size: 7940
sha: 9379326f020284d79ca4168af4bb0770663cbc35
upstream: https://github.com/smkalami/skills/blob/main/skills/evo-search/SKILL.md

````text
---
name: evo-search
description: >
  Solves complex, open-ended problems using an evolutionary search mechanism inspired by
  genetic algorithms. Generates a diverse population of candidate answers, scores them
  against a rubric, then iteratively applies selection, crossover, and mutation to breed
  progressively better solutions. Use this skill whenever the user wants to explore a
  solution space deeply, asks for the "best" answer to a subjective or multi-dimensional
  problem, wants to evaluate competing approaches and distill the strongest, or uses any
  of these triggers: "evolutionary search", "genetic algorithm", "evolve an answer",
  "breed solutions", "population-based search", or phrases like "give me multiple
  approaches and refine the best one". Also trigger when the problem is complex,
  open-ended, or has no obvious single correct answer and the user wants a high-quality,
  well-explored result, not just a quick response.
---

# Evo-Search

Runs a genetic-algorithm-style loop over candidate responses: generate a diverse initial population, score each against a rubric, then repeatedly select, crossover, and mutate to improve quality across generations. Output the top 3 final solutions.

---

## Step 0: Problem Intake & Rubric

Identify problem type, constraints, audience, and scope. If ambiguous, ask one question.

### Rubric Construction

Detect which mode applies:

| Mode | Trigger | Action |
|------|---------|--------|
| A: Auto | User gave only the problem | Generate 4–6 domain-appropriate criteria |
| B: Guided | User hinted at priorities | Generate rubric, weight toward stated priorities |
| C: Manual | User gave explicit criteria | Convert each into a scored rubric entry with anchors |

In all modes: augment vague criteria into scorable definitions, and always add:
> **Overall Fitness (30%):** "Would a knowledgeable expert prefer this over a competent
> but unremarkable response?" Scored holistically. Prevents narrow-criteria gaming.

**Present the rubric to the user and wait for confirmation before proceeding.**

Rubric format:
```
| Criterion      | Description              | Weight | Max |
|----------------|--------------------------|--------|-----|
| [Name]         | [Definition + anchors]   | X%     | 10  |
| Overall Fitness| Expert holistic score    | 30%    | 10  |
Weighted Total = Σ(score × weight)  [max = 10.00]
```

---

## Step 1: Initial Population

Generate **6 candidates** (default) using these diversity frames, one per candidate:

| # | Frame |
|---|-------|
| 1 | Conventional / mainstream |
| 2 | Contrarian / challenges assumptions |
| 3 | First-principles / bottom-up |
| 4 | Analogy-led / draws from another domain |
| 5 | Risk-focused / emphasizes what could go wrong |
| 6 | Synthesis / combines multiple angles |

Generate all candidates before scoring any. Then score each and display:

```
GENERATION 0
| # | Frame        | Fitness | Strength       | Weakness      |
|---|--------------|---------|----------------|---------------|
| 1 | Conventional | X.X     | [one phrase]   | [one phrase]  |
```

---

## Step 2: Evolution Loop

**Default: 5 iterations.** Repeat until stopping criteria are met.

### 2.1 Selection
Tournament selection: sample 2 candidates, keep the higher scorer. Repeat to get 4 parents.
Elitism: carry the top 2 candidates forward untouched every generation.

### 2.2 Crossover
Produce 4 offspring (pair parents: 1+2, 3+4, 1+3, 2+4). For each pair, synthesize a child
that inherits the key strength of each parent without their primary weaknesses. Rotate
crossover strategies across iterations (trait synthesis → section splice → schema inheritance).

### 2.3 Mutation
Apply mutation to each offspring with probability **0.2** (~1 of 4 offspring per generation).

| Mode | When to use | What to do |
|------|-------------|------------|
| Exploitative (~60%) | Offspring has a diagnosable weak criterion | Target and fix that specific criterion |
| Exploratory (~40%) | No clear weakness, or population is converging | Random perturbation: swap rhetorical stance, domain lens, level of abstraction, or target audience |

**Multi-feature mutation:** ~1 in 3 mutation events, mutate two features simultaneously.
Use when the population has converged for 2+ generations, two criteria score equally low,
or an exploratory mutation is being applied.

### 2.4 Evaluate & Merge
Score all offspring. Merge with current population. Keep top 6 by fitness score.
Elites from 2.1 are guaranteed to survive.

### 2.5 Convergence Check
If top 3 candidates are within 0.4 fitness of each other AND content is substantially
similar, inject 1–2 fresh randomly-framed candidates ("immigrants") before merging.

Display per-generation summary:
```
GENERATION [N]
| # | Origin        | Fitness | Δ   | Key Change         |
|---|---------------|---------|-----|--------------------|
| 1 | Elite         | X.X     | -   | -                  |
| 2 | Crossover A+B | X.X     | +Y  | [what changed]     |
Best: Candidate [N] (X.X)
```

---

## Stopping Criteria

Stop early if any condition is met:
- Max iterations reached (default: 5)
- Best fitness ≥ 9.0
- Best fitness improved less than 0.2 over 2 consecutive generations

Note the reason when stopping early.

---

## Step 3: Output

### 3.1 Contrast Table (show before full answers)
```
TOP 3 SOLUTIONS
| Rank | Score | Defining Strength    | Best Used When              |
|------|-------|----------------------|-----------------------------|
| #1   | X.X   | [one phrase]         | [context where #1 wins]     |
| #2   | X.X   | [one phrase]         | [context where #2 wins]     |
| #3   | X.X   | [one phrase]         | [context where #3 wins]     |
```

### 3.2 Full Solutions
Output the top `top_k` solutions in full (default: 3), labeled with rank and score.

### 3.3 Evolution Trace
```
EVOLUTION SUMMARY
| Generation | Best Fitness | Key Improvement     |
|------------|--------------|---------------------|
| 0 (init)   | X.X          | [note]              |
| ...        | ...          | ...                 |
Final: X.X / 10.0
```

### 3.4 Rubric Breakdown
Show per-criterion scores for the #1 solution only.

---

## Parameters

| Parameter      | Default      | Range                              | Effect                              |
|----------------|--------------|------------------------------------|-------------------------------------|
| population     | 6            | 4–10                               | Candidates per generation           |
| iterations     | 5            | 1–10                               | Evolution cycles                    |
| mutation_rate  | 0.2          | 0–1                                | Fraction of offspring mutated       |
| mutation_mode  | mixed        | exploitative / exploratory / mixed | Mutation strategy bias              |
| multi_mutation | occasional   | never / occasional / frequent      | How often 2 features mutate at once |
| elites         | 2            | 1–3                                | Candidates preserved each generation|
| top_k          | 3            | 1–5                                | Final solutions shown in full       |
| rubric_mode    | auto         | auto / guided / manual             | How the rubric is built             |
| show_trace     | true         | true / false                       | Show evolution summary              |

Users set parameters in plain language. Examples:
- *"Quick run, 3 iterations"* → iterations=3
- *"Large population, thorough search"* → population=8–10
- *"Be more exploratory"* → mutation_mode=exploratory
- *"Just show me the winner"* → top_k=1

---

## Scoring Guidance

Score honestly. A mediocre-but-coherent answer scores 5-6. Inflated scores destroy the selection signal and the algorithm stops working. The crossover step is where the most value is created. Synthesize genuine strengths; don't concatenate text.
````

## File: README.md
upstream: https://github.com/smkalami/skills/blob/main/README.md

````text
# Agent Skills by Mostapha Kalami Heris

A collection of agent skills that give AI agents structured, reusable workflows for tackling complex problems. These skills go beyond simple prompting to deliver consistently higher-quality results.

*More skills will be added over time.*

---

## Table of Contents

- [Agent Skills by Mostapha Kalami Heris](#agent-skills-by-mostapha-kalami-heris)
  - [Table of Contents](#table-of-contents)
  - [Skills](#skills)
    - [`evo-search`](#evo-search)
    - [`tournament-search`](#tournament-search)
    - [`prompt-decorators`](#prompt-decorators)
  - [Installation](#installation)
    - [CLI Tools (Claude Code, Gemini CLI, VS Code, etc.)](#cli-tools-claude-code-gemini-cli-vs-code-etc)
    - [Online AI Assistant Platforms (ChatGPT, Claude, Gemini, etc.)](#online-ai-assistant-platforms-chatgpt-claude-gemini-etc)
  - [How to Cite](#how-to-cite)
  - [License](#license)

---

## Skills

> **Note on token usage:** Skills like `evo-search` and `tournament-search` generate and evaluate multiple candidate responses across several rounds. Certain decorators in `prompt-decorators` also add extra reasoning or refinement steps. This increases token consumption significantly compared to a single plain prompt. The benefit is higher response quality, but it is not free. If you are on a metered subscription, running these skills can cost noticeably more. Consider using lighter configurations (for example, fewer iterations, a smaller population, or simpler decorators) when your token budget is limited.

### `evo-search`

Solves complex, open-ended problems using a **genetic-algorithm-style search loop**.

It generates a diverse initial population of candidate answers, scores each one against a weighted rubric, and then repeatedly applies selection, crossover, and mutation to produce stronger solutions. The final output includes the top 3 solutions with scores, a contrast table, and an evolution trace.

**When this skill is triggered:**
- The user asks for an "evolutionary search", "genetic algorithm", "evolve an answer", or "breed solutions"
- The user says "give me multiple approaches and refine the best one"
- The problem is complex or open-ended with no single correct answer, and the user wants a deeply explored result

**Key parameters** (set in plain language):

| Parameter | Default | Effect |
|-----------|---------|--------|
| `population` | 6 | Candidates per generation |
| `iterations` | 5 | Evolution cycles |
| `mutation_rate` | 0.2 | Fraction of offspring mutated |
| `top_k` | 3 | Final solutions shown in full |

**Install:**
- **CLI tools:** run in your terminal:
  ```sh
  npx skills@latest add smkalami/skills/evo-search
  ```
- **AI assistant platforms:** download and upload [`evo-search.skill`](dist/evo-search.skill)

**Example usage:**
```
Use evo-search to invent a new programming paradigm that blends constraint propagation
with biological growth patterns. Something that does not exist yet but could realistically
be implemented. Define its core model, syntax philosophy, and a killer use case.
```

```
Evolve an answer: design a radically new way for human teams to make high-stakes decisions
under uncertainty, combining ideas from mechanism design, cognitive science, and swarm
intelligence, without relying on voting, consensus, or hierarchy.
```

---

### `tournament-search`

Solves complex, open-ended problems using a **knockout bracket tournament**.

It generates a diverse set of candidate answers, draws a random bracket, and runs head-to-head matches. Each match produces a hybrid solution that combines the strengths of both competitors, and the strongest of the three advances. A 3rd-place playoff is also included. This skill is faster than `evo-search` and works best when you want a clear winner quickly.

**When this skill is triggered:**
- The user asks for a "tournament", "bracket-style search", "knockout search", or says "let solutions compete"
- The user says "find the best answer by elimination" or "which solution wins?"
- The problem is open-ended and the user wants a clear winner without deep multi-generation refinement

**Key parameters** (set in plain language):

| Parameter | Default | Effect |
|-----------|---------|--------|
| `population` | 8 | Initial candidates (must be a power of 2) |
| `top_k` | 3 | Podium solutions shown in full |
| `trait_logging` | off | Log best ideas from eliminated candidates |

**Install:**
- **CLI tools:** run in your terminal:
  ```sh
  npx skills@latest add smkalami/skills/tournament-search
  ```
- **AI assistant platforms:** download and upload [`tournament-search.skill`](dist/tournament-search.skill)

**Example usage:**
```
Run a tournament to find the best architecture for a city-scale autonomous mobility system
that handles mixed traffic of human drivers, autonomous vehicles, cyclists, and pedestrians.
Each candidate must address safety, latency, failure modes, and rollout strategy.
```

```
Let solutions compete: propose a new economic model for funding open-source software
that does not rely on donations, corporate sponsorship, or government grants.
Each proposal must be self-sustaining and implementable within 5 years.
```

---

### `prompt-decorators`

> The original (non-skill) version of this framework is available at [smkalami/prompt-decorators](https://github.com/smkalami/prompt-decorators).
>
> **Paper:** Mostapha Kalami Heris, "Prompt Decorators: A Declarative and Composable Syntax for Reasoning, Formatting, and Control in LLMs", arXiv preprint [arXiv:2510.19850](https://arxiv.org/abs/2510.19850) (2025).

Activates a **structured decorator framework** that controls how the AI reasons, responds, and formats its output, using lightweight `+++` markers.

Decorators are placed at the top of a prompt and applied at the same time. Each one controls a different aspect of the response, such as reasoning style, tone, output format, or verification. They can be applied to a single message or kept active for an entire chat session.

**When this skill is triggered:**
- The prompt contains one or more `+++` markers (for example, `+++Reasoning`, `+++StepByStep`, or `+++Tone(style=formal)`)
- The user asks to "activate", "list", or "clear" decorators
- The user references the "prompt decorator framework" or says "use decorator" / "apply +++"

**Decorator categories:**

| Category | Decorators |
|----------|------------|
| Reasoning and structure | `+++Reasoning`, `+++StepByStep`, `+++Socratic`, `+++Debate` |
| Evaluation and refinement | `+++Critique`, `+++Refine(iterations=N)`, `+++Candor(level=L)` |
| Exploration and planning | `+++Brainstorm`, `+++Planning`, `+++Interactive`, `+++Import(topic=T)` |
| Rewriting and clarification | `+++Rewrite` |
| Output control | `+++OutputFormat(format=F)`, `+++Tone(style=S)` |
| Verification | `+++FactCheck`, `+++CiteSources`, `+++Validate` |

**Session management:**
- `+++ChatScope`: persist decorators across the entire session
- `+++Clear`: remove all active session-scoped decorators
- `+++ActiveDecs`: list currently active decorators
- `+++AvailableDecs`: list all available decorators

**Install:**
- **CLI tools:** run in your terminal:
  ```sh
  npx skills@latest add smkalami/skills/prompt-decorators
  ```
- **AI assistant platforms:** download and upload [`prompt-decorators.skill`](dist/prompt-decorators.skill)

**Example usage:**
```
+++Rewrite
+++Reasoning

Please design a teaching plan for a 10-week course on machine learning
to be taught to college students with no prior experience in the subject.
```

```
+++Brainstorm
+++Refine(iterations=3)

Propose novel interaction paradigms for human-AI collaboration in creative work
that go beyond chat and prompt-response. Think beyond current interfaces.
```

---

## Installation

Each skill above lists both installation options. There are two approaches depending on how you use AI tools.

### CLI Tools (Claude Code, Gemini CLI, VS Code, etc.)

Run the `npx` command listed beside the sk
````
