crimeacs/auto-improve

O que auto-improve faz?

Melhoria autônoma e controlada por juiz para qualquer artefato de texto. Consulte o README.md para o guia completo; esta é a referência rápida para o agente.

Quando usar

O usuário quer algo mensuravelmente melhor, não apenas reescrito — e está disposto a expressar "melhor" como uma rubrica. Bons usos: e-mails frios, texto de landing pages, prompts, definições de skill, posts de blog, cartas de apresentação, documentação, contratos, cardápios.

Executar

export GEMINI_API_KEY=...        # https://aistudio.google.com/apikey
python3 improve.py \
  --artifact caminho/para/arquivo.md \   # deve estar dentro de um repositório git
  --tag v1 \                     # → branch improve/v1, resultados/v1.tsv
  --max-iterations 8 \
  --criteria caminho/para/rubrica.md   # OPCIONAL — omita para inferir automaticamente uma rubrica; ou adicione
                                 # --goal "como é o bom" para direcionar a inferida

Se você não passar --criteria, o auto-improve escreve uma rubrica a partir do artefato primeiro e a salva em resultados/<tag>.rubric.md — leia-a para ver para que está otimizando. Verifique uma execução finalizada: python3 improve.py --status --tag v1. O resultado fica no branch improve/<tag> do git — git diff main improve/v1 -- <arquivo>.

Como decide (a parte anti-slop)

1. Mutar — as melhores N edições candidatas, aplicadas como diffs cirúrgicos (à prova de falhas).
2. Pontuar — cada candidata avaliada contra a rubrica por uma chamada de modelo separada.
3. Decidir — a melhor candidata é julgada em pares contra a atual campeã (ambas as ordens, sem viés); mantida apenas se realmente vencer, caso contrário, revertida.

O mutador nunca avalia seu próprio trabalho, e reescritas confiantes mas piores são descartadas — portanto, a subida é real e cada commit é um ganho verificado.

Escrevendo a rubrica

Um arquivo markdown de dimensões ponderadas totalizando 100 — ancoradas (50/70/90), enquadradas como recompensa, específicas. Veja criteria/README.md e os exemplos práticos em criteria/.

Regras principais

• O mutador e o avaliador nunca compartilham contexto.
• Um artefato, uma rubrica, uma --tag por execução.
• O branch do git é a fonte da verdade; resultados/<tag>.tsv é o registro da subida (não rastreado).
• Nunca edite fora do artefato; pequenos diffs cirúrgicos, não reescritas completas.