# Grade Iterate

Use when a launched managed agent needs grading against a rubric and improving ('grade...

- Repository: https://github.com/alirezarezvani/claude-skills (29114 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add alirezarezvani/claude-skills --skill grade-iterate -g -a claude-code -y`
Codex: `npx skills add alirezarezvani/claude-skills --skill grade-iterate -g -a codex -y`
Cursor: `npx skills add alirezarezvani/claude-skills --skill grade-iterate -g -a cursor -y`
Gemini CLI: `npx skills add alirezarezvani/claude-skills --skill grade-iterate -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add alirezarezvani/claude-skills`

## Description

Use when a launched managed agent needs grading against a rubric and improving ('grade my agent', 'is it good enough'). Builds the outcome with outcome_builder.py, reads verdicts with verdict_reader.py and runs held-back evals from eval_scaffold.py.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Phase 3, Grade → Iterate (the bounded loop)

This is the plugin's **loop**: CMA's `outcome` primitive self-grades the agent's
work in an isolated context and feeds failing verdicts back for the next attempt.
It is **always bounded** by `max_iterations` (1..20), never "improve forever".

See [`../../references/loops-and-workflows.md`](../../references/loops-and-workflows.md)
and the outcome section of
[`../../references/cma-primitives.md`](../../references/cma-primitives.md).

## Workflow

1. **Define the outcome.**
   ```bash
   python3 scripts/outcome_builder.py \
     --sheet ./my-agent/build-sheet.json --max-iterations 5 \
     --out ./my-agent/payloads/outcome.json
   ```
   The **rubric is required**; `max_iterations` is clamped to 1..20. Send the
   payload as a `user.define_outcome` event (append to the running session).
2. **Read every verdict first.**
   ```bash
   python3 scripts/verdict_reader.py --result ./my-agent/last-verdict.json
   ```
   Tables the rubric outcome and recommends: **SHIP** (`satisfied`), **SHARPEN**
   then re-run (`needs_revision`), **ESCALATE** (`max_iterations_reached` /
   `failed`), **RESUME** (`interrupted`). With ≤1 iteration left it flips to
   "make the single highest-value fix or escalate now".
3. **Loop invariant.** Each iteration must move ≥1 rubric line fail→pass, or the
   run halts at the cap and escalates. Don't burn the budget on cosmetic edits.
4. **Once a version passes, run held-back eval.**
   ```bash
   python3 scripts/eval_scaffold.py \
     --sheet ./my-agent/build-sheet.json --out ./my-agent/eval.json --concurrency 5
   ```
   Held-back cases (never seen during iteration) run in parallel, capped at the
   25-thread CMA ceiling, each graded against the same rubric.
5. **Decide.** SHIP as v0, or promote to a scheduled deployment (Phase 4). Record
   the verdict on the goal: `goal_state.py set --phase run-without-you`.

## Hard rules

The rest: https://github.com/alirezarezvani/claude-skills/blob/HEAD/agent-launcher/skills/grade-iterate/SKILL.md