name	auto-improve
description	GAN-style iterative improvement loop for any text artifact. Mutates a file, grades each change against a rubric with a SEPARATE model, keeps only verified wins (pairwise-judged), reverts the rest. The git history is the improvement log. Use when the user wants to autonomously improve the quality of a document, email, prompt, landing page, README, contract, or any text file.
user-invocable	true

auto-improve

Autonomous, judge-gated self-improvement for any text artifact. See README.md for the full guide; this is the agent-facing quick reference.

When to use

The user wants something measurably better, not just rewritten — and is willing to express "better" as a rubric. Good fits: cold emails, landing copy, prompts, skill definitions, blog posts, cover letters, docs, contracts, menus.

Run it

export GEMINI_API_KEY=...        # https://aistudio.google.com/apikey
python3 improve.py \
  --artifact path/to/file.md \   # must be inside a git repo
  --tag v1 \                     # → branch improve/v1, results/v1.tsv
  --max-iterations 8 \
  --criteria path/to/rubric.md   # OPTIONAL — omit to auto-infer a rubric; or add
                                 # --goal "what good looks like" to steer the inferred one

If you don't pass --criteria, auto-improve writes a rubric from the artifact first and saves it to results/<tag>.rubric.md — read it to see what it's optimizing for. Check a finished run: python3 improve.py --status --tag v1. The result lives on the improve/<tag> git branch — git diff main improve/v1 -- <file>.

How it decides (the anti-slop part)

Mutate — best-of-N candidate edits, applied as surgical diffs (crash-proof).
Score — each candidate graded against the rubric by a separate model call.
Decide — the best candidate is pairwise-judged against the champion (both orderings, debiased); kept only if it genuinely wins, else reverted.

The mutator never grades its own work, and confident-but-worse rewrites are discarded — so the climb is real and every commit is a verified gain.

Writing the rubric

A markdown file of weighted dimensions totaling 100 — anchored (50/70/90), reward-framed, specific. See criteria/README.md and the worked examples in criteria/.

Key rules

The mutator and evaluator never share context.
One artifact, one rubric, one --tag per run.
The git branch is the source of truth; results/<tag>.tsv is the climb log (untracked).
Never edit outside the artifact; small surgical diffs, not wholesale rewrites.

auto-improve

Autonomous, judge-gated self-improvement for any text artifact. See README.md for the full guide; this is the agent-facing quick reference.

When to use

Run it

export GEMINI_API_KEY=... # https://aistudio.google.com/apikey python3 improve.py \ --artifact path/to/file.md \ # must be inside a git repo --tag v1 \ # → branch improve/v1, results/v1.tsv --max-iterations 8 \ --criteria path/to/rubric.md # OPTIONAL — omit to auto-infer a rubric; or add # --goal "what good looks like" to steer the inferred one

How it decides (the anti-slop part)

Mutate — best-of-N candidate edits, applied as surgical diffs (crash-proof).

Score — each candidate graded against the rubric by a separate model call.

Decide — the best candidate is pairwise-judged against the champion (both orderings, debiased); kept only if it genuinely wins, else reverted.

The mutator never grades its own work, and confident-but-worse rewrites are discarded — so the climb is real and every commit is a verified gain.

Writing the rubric

A markdown file of weighted dimensions totaling 100 — anchored (50/70/90), reward-framed, specific. See criteria/README.md and the worked examples in criteria/.

Key rules

The mutator and evaluator never share context.

One artifact, one rubric, one --tag per run.

The git branch is the source of truth; results/<tag>.tsv is the climb log (untracked).

Never edit outside the artifact; small surgical diffs, not wholesale rewrites.