# simmer

Adopt this skill: https://proskills.md/skills/other/2389-research-simmer-skills-simmer

Page: https://proskills.md/skills/other/2389-research-simmer-skills-simmer
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/simmer/SKILL.md
size: 8632
upstream: https://github.com/2389-research/simmer/blob/main/skills/simmer/SKILL.md

````text
---
name: simmer
description: >
  Use when user says "simmer this", "refine this", "hone this", "iterate on this",
  or asks to improve a specific artifact over multiple rounds. Runs an iterative
  refinement loop with investigation-first judges that read the code, understand
  the problem, and propose evidence-based improvements. Auto-selects single judge
  or multi-judge board based on complexity. Works on any artifact type: documents,
  prompts, specs, emails, creative writing, API designs, pipelines, codebases.
  Supports multi-file workspace targets, runnable evaluators, and open-ended
  optimization (model selection, pipeline topology, prompt tuning).
---

# Simmer

Iterative refinement loop — take an artifact (single file or workspace) and hone it repeatedly against user-defined criteria until it's as good as it can get.

**Related skills (test-kitchen family):**
- `test-kitchen:omakase-off` — don't know what you want → parallel designs → react → pick
- `test-kitchen:cookoff` — know what you want, it's code → parallel implementations → fixed criteria → steal the best
- `simmer` — know what you want, it's anything → user-defined criteria → iterate until good

## Flow

```
"Simmer this" / "Refine this" / "Optimize this pipeline"
    ↓
┌─────────────────────────────────────┐
│  SETUP (identify + criteria)        │
│  Load simmer-setup subskill         │
│                                     │
│  Output: artifact, rubric, N iters, │
│  evaluator (optional),              │
│  background (optional)              │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│  LOOP (default 3 iterations)        │
│                                     │
│  Each iteration:                    │
│  1. Dispatch generator subagent     │
│  2. Run evaluator (if present)      │
│  3. Dispatch judge subagent         │
│  4. Load reflect subskill           │
│                                     │
│  Generator gets: candidate + ASI    │
│           + background              │
│  Judge gets: candidate + rubric     │
│       + evaluator output (if any)   │
│  Reflect gets: full score history   │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│  OUTPUT                             │
│  Best candidate → result file       │
│  Score trajectory displayed         │
└─────────────────────────────────────┘
```

## When to Use

Trigger when user wants iterative refinement of any kind:
- "Simmer this", "refine this", "hone this", "iterate on this"
- "Make this better", "improve this over a few rounds"
- "Polish this", "tighten this up"
- "Optimize this pipeline", "find the best model for this task"
- "Tune this configuration", "improve these prompts against this test suite"
- Any request to iteratively improve an artifact or workspace

**Judge mode is auto-selected by setup** based on problem complexity:

| Condition | JUDGE_MODE |
|-----------|-----------|
| text/creative, ≤2 criteria, short artifact (email, tweet, tagline) | `single` |
| text/creative, 3 criteria or long/complex artifact | `board` |
| code/testable (any) | `board` |
| pipeline/engineering (any) | `board` |
| User says "with a single judge" | `single` (override) |
| User says "with a judge board" or "with a panel" | `board` (override) |

**Plateau upgrade:** If the loop started with a single judge and detects a plateau (3 iterations without improvement), offer: "Scores have plateaued. Switch to judge board for deeper diagnosis?" If the user accepts, switch to `JUDGE_MODE: board` for remaining iterations.

**Not simmer:** If the artifact is code and the user wants parallel implementations, use cookoff instead.

## Orchestration

**Announce:** "I'm using the simmer skill to set up iterative refinement."

**Track progress** (TodoWrite if available, otherwise inline):
1. Setup — identify artifact, elicit criteria, determine evaluation method
2. Refinement loop (N iterations)
3. Output best version with score trajectory

### Phase 1: Setup

**Invoke `simmer:simmer-setup`.**

Do not attempt to identify the artifact or ask about criteria yourself — that is the setup subskill's job.

**Shortcut:** If the user (or calling system) has already provided artifact, criteria (each with at least one sentence describing what a high score looks like), iteration count, mode, and optionally evaluator/background, skip the setup subskill entirely. Construct the setup brief directly and proceed to Phase 2.

Setup returns a brief:
```
ARTIFACT: [content, file path, or directory path]
ARTIFACT_TYPE: [single-file | workspace]
CRITERIA:
  - [criterion 1]: [what better looks like]
  - [criterion 2]: [what better looks like]
  - [criterion 3]: [what better looks like]
PRIMARY: [criterion name — omit if equally weighted]
EVALUATOR: [command to run — omit for judge-only mode]
BACKGROUND: [constraints, available resources, domain knowledge — omit if not needed]
OUTPUT_CONTRACT: [valid output format description — omit for text/creative]
VALIDATION_COMMAND: [quick check command — omit if no cheap validation exists]
SEARCH_SPACE: [what's in scope to explore — omit if unconstrained]
JUDGE_MODE: [single | board — auto-selected by setup based on complexity. User can override]
JUDGE_PANEL: [optional custom judge definitions — omit to use defaults for problem class]
ITERATIONS: [N]
MODE: [seedless | from-file | from-paste | from-workspace]
OUTPUT_DIR: [path, default: docs/simmer]
```

### Phase 2: Refinement Loop

**For single-file mode:**
```bash
mkdir -p {OUTPUT_DIR}
```

**For workspace mode:**
```bash
# Create initial commit to snapshot the seed state
cd {ARTIFACT}
git add -A && git commit -m "simmer: iteration 0 — seed state"
```

**Iteration counting:**

"N iterations" means N generate-judge-reflect cycles AFTER the initial seed judgment. The seed judgment is iteration 0 (not counted toward N). So `ITERATIONS: 3` means:
- Iteration 0: Judge the seed (no generator)
- Iteration 1: Generate → Judge → Reflect
- Iteration 2: Generate → Judge → Reflect
- Iteration 3: Generate → Judge → Reflect
- Total: 3 generation passes + 1 seed judgment = 4 judge rounds

For seedless mode: iteration 1 generates the initial candidate AND judges it. `ITERATIONS: 3` means 3 generation passes total.

**Iteration 0 (seed):**

*Single-file mode:*
- Write the seed artifact to `{OUTPUT_DIR}/iteration-0-candidate.md`
- If seedless: dispatch generator subagent to produce initial candidate from description + criteria, then judge it
- If from-file or from-paste: the seed IS the starting artifact — judge it directly (no generator)

*Workspace mode:*
- The seed is the current state of the workspace directory
- If from-workspace: judge the current state directly (no generator)
- If seedless: dispatch generator to scaffold the initial workspace, then judge it

**Each iteration:**

**Step 1: Generator (subagent)**

Invoke `simmer:simmer-generator` as a subagent.

*Single-file subagent prompt:*
```
You are the generator in a simmer refinement loop.

Invoke the skill: simmer:simmer-generator

ITERATION: [N]
ARTIFACT_TYPE: single-file
CRITERIA:
[rubric from setup]

CURRENT CANDIDATE:
[full text of current best candidate]

JUDGE FEEDBACK (ASI from previous round):
[ASI text, or "First iteration — generate initial candidate" if seedless iteration 1]

Write your improved candidate to: {OUTPUT_DIR}/iteration-[N]-candidate.md
(or appropriate extension matching artifact type)

Report: what specifically changed and why (2-3 sentences).
```

*Workspace subagent prompt:*
```
You are the generator in a simmer refinement loop.

Invoke the skill: simmer:simmer-generator

ITERATION: [N]
ARTIFACT_TYPE: workspace
WORKSPACE: [directory path]
CRITERIA:
[rubric from setup]

BACKGROUND:
[constraints, available resources, domain knowledge from setup]

OUTPUT_CONTRACT:
[valid output format — omit if not specified in setup]

VALIDATION_COMMAND:
[quick check command — omit if not specified in setup]

SEARCH_SPACE:
[what's in scope to
````

## File: README.md
upstream: https://github.com/2389-research/simmer/blob/main/README.md

````text
# Simmer

You wrote a prompt. It works. But is it *good*? Simmer runs your artifact through multiple rounds of criteria-driven refinement — each round, a panel of judges reads your code, understands the problem, and proposes specific improvements.

[Read the story behind Simmer →](https://2389.ai/posts/simmer-skill/)

Iterative artifact refinement — take any artifact or workspace and hone it over multiple rounds using criteria-driven feedback.

## Installation

```bash
/plugin marketplace add 2389-research/claude-plugins
/plugin install simmer@2389-research
```

## What This Plugin Provides

One skill (`simmer`) with five subskills that run the refinement loop:

- **Setup** — identify the artifact (file or workspace), elicit 2-3 quality criteria, determine evaluation method
- **Generator** — produce an improved version based on the judge's ASI (Actionable Side Information — the single highest-leverage fix)
- **Judge** — score the candidate 1-10 per criterion, produce the ASI
- **Judge Board** — panel of perspective-diverse judges; drop-in replacement for Judge when JUDGE_MODE is board
- **Reflect** — record the trajectory, track the best candidate across iterations

## Trigger Phrases

Say any of these to start a simmer loop:

> "simmer this", "refine this", "hone this", "iterate on this", "make this better", "improve this over a few rounds", "polish this", "tighten this up", "optimize this pipeline", "find the best model for this task", "tune this configuration"

Any request to **iteratively improve** an artifact triggers simmer.

## When to Use Simmer vs. Cookoff vs. Omakase-Off

| Situation | Use | Why |
|-----------|-----|-----|
| You have an artifact and want it better | **simmer** | Iterative refinement against criteria |
| You want parallel code implementations competing | **cookoff** | Parallel generation + fixed criteria + pick winner |
| You don't know what you want yet | **omakase-off** | Parallel designs + react + discover preference |

**Rule of thumb:** Simmer = serial iteration. Cookoff/omakase-off = parallel exploration.

## Quick Example: Single File

```
User: "Simmer this" [pastes a pitch email]

Claude: I'm using the simmer skill to set up iterative refinement.

What does "better" mean for this? I'd suggest:
1. Value prop clarity
2. Tone match
3. Call to action strength

User: "Those work"

[Iteration 0: Judge scores seed — 4.0/10]
[Iteration 1: Generator fixes value prop → 5.3/10]
[Iteration 2: Generator fixes CTA → 6.3/10]
[Iteration 3: Generator fixes tone → 7.3/10]

Trajectory:
| Iter | Value Prop | Tone | CTA | Composite | Key Change |
|------|-----------|------|-----|-----------|------------|
| 0    | 4         | 5    | 3   | 4.0       | seed       |
| 1    | 7         | 5    | 4   | 5.3       | specific problem statement |
| 2    | 7         | 6    | 6   | 6.3       | low-friction CTA |
| 3    | 7         | 7    | 8   | 7.3       | peer-sharing tone |

Best candidate: iteration 3 (7.3/10)
3 iterations complete. Run 3 more?
```

## Quick Example: Workspace with Evaluator

```
User: "Simmer this pipeline — find the best setup for this task"

Claude inspects the workspace, finds evaluate.sh and config.json,
and proposes criteria + evaluation method:

  Evaluator: ./evaluate.sh
  Criteria: accuracy, cost efficiency, latency
  Search space: models, prompt text, pipeline topology

User: "Looks good, coverage is the priority. 5 iterations."

[Iteration 0: Run evaluator on seed, judge scores — 3.7/10]
[Iteration 1: Generator swaps to cheaper model → 5.3/10]
[Iteration 2: Generator splits into 2-step chain → 7.0/10]
[Iteration 3: Generator adds few-shot examples → 7.7/10]
...

Best candidate: iteration 4 (8.1/10)
```

## Works On Anything

| Artifact type | Suggested criteria |
|---|---|
| Document / spec | clarity, completeness, actionability |
| Creative writing | narrative tension, specificity, voice consistency |
| Email / comms | value prop clarity, tone match, call to action strength |
| Prompt / instructions | instruction precision, output predictability, edge case coverage |
| API design | contract completeness, developer ergonomics, consistency |
| Pipeline / workflow | coverage, efficiency, noise |
| Configuration / infra | correctness, resource efficiency, maintainability |

## Evaluation Modes

| Mode | When to use |
|------|------------|
| **Judge-only** (default) | Text artifacts — judge scores against criteria |
| **Runnable** | Code/pipelines — judge interprets script output |
| **Hybrid** | Both — run script AND judge results against criteria |

No format contract on evaluator output. The judge reads whatever your script produces — test results, metrics, error logs, anything.

## Judge Board

Simmer auto-selects between a single judge and a multi-judge board based on complexity:

- **Simple** (short email, tweet, ≤2 criteria) → single judge, fast
- **Complex** (3 criteria, long artifact, code, pipelines) → judge board with deliberation

The board constructs three judges tailored to your specific problem — not from a fixed menu, but by reading your artifact, criteria, and constraints and designing judges with diverse perspectives. An extraction prompt gets different judges than a DND adventure hook.

Judges investigate before scoring — they read the evaluator script, ground truth, prior candidates, and config files to understand the problem deeply. A judge who reads the evaluator discovers scoring mechanics on iteration 0 instead of learning them through 3 iterations of trial and error.

If a single-judge run hits a plateau (3 iterations without improvement), simmer offers to upgrade to the board mid-run with 2 extra iterations.

## Defaults and Safety

**Default iteration count:** 3 rounds per batch. After each batch, simmer asks whether to continue. You can request a specific count ("simmer this for 10 rounds") or stop early at any prompt.

**Regression safety:** The reflect subskill tracks the best candidate seen so far. If a new iteration scores lower than the current best, the best-so-far is preserved — the loop never loses progress. At the end, `result.md` always contains the highest-scoring candidate, not just the latest one.

## Advanced Features

| Feature | When you need it |
|---------|-----------------|
| **Workspace targets** | Refining a multi-file directory — iterations tracked as git commits so you can diff any two rounds |
| **Runnable evaluators** | Your artifact has a test script — point simmer at it (`python evaluate.py`) and the judge interprets output |
| **Background constraints** | The generator needs to know what's available (models, budget, latency targets) to make realistic choices |
| **Output contracts** | Valid output has a defined shape (e.g., JSON schema) — violations score 1/10, forcing format fixes first |
| **Validation commands** | A cheap pre-check (`./validate.sh`) catches broken pipelines in seconds before the full evaluator runs |
| **Search space tracking** | Explicit bounds on what to explore — reflect tracks tried vs. untried regions so the judge steers toward gaps |

See the [v2 design spec](./docs/specs/2026-03-16-simmer-v2-design.md) for full details on each feature.

## Output Directory Structure

**Single-file mode** (default output dir: `docs/simmer`):
```
docs/simmer/
  iteration-0-candidate.md     # Seed (original artifact)
  iteration-1-candidate.md     # Each improved candidate
  iteration-2-candidate.md
  iteration-3-candidate.md
  trajectory.md                # Running score table
  result.md                    # Final best candidate (highest score, not necessarily latest)
```

**Workspace mode:**
```
./pipeline/                    # Target directory (modified in place)
  [project files]              # Tracked via git commits per iteration

docs/simmer/                   # Tracking files (separate from workspace)
  trajectory.md                # Running score table
```

Workspace iterations are tracked as git commits rather than separate files.

## How It Work
````
