| name | zicato-step-loop |
| description | Drive the zicato evolve loop one stage at a time (propose → tournament) for inspecting or debugging a single round. Use only when you need to look inside what `zicato evolve` does internally; for normal operation run `zicato evolve`. |
zicato step-loop (manual round, for debug only)
zicato evolve is the happy path: it auto-resolves the contract, auto-opens an
epoch, then runs analyze-telemetry → propose → (apply) → tournament → promote
for --rounds rounds. This skill drives those stages by hand, one at a
time, so you can inspect each artifact between stages. Reach for it only when
debugging a single round — never as the normal way to run zicato.
Guardrail: propose and tournament call real LLMs and spend budget. Treat
them as live runs — get the operator's explicit go-ahead before invoking them
(AGENTS.md rule 1). Everything in the "inspect" steps below is read-only and
safe. Use .venv/bin/zicato; never uv sync mid-task.
The real command names (verify before you script)
The design docs (docs/design/CLI.md §3.5–3.8) describe zicato run,
zicato analyze, and zicato patch apply as separate steps. Those are not
in the shipped CLI. The real surface is:
| Doc form | Real CLI | Notes |
|---|
zicato run --generation vN --entry <id> [--tail] | (none) | No standalone runner. Runs happen inside tournament / evolve, which execute every board entry against each generation. |
zicato analyze | zicato analyze-telemetry | Decision-telemetry analyzer for the current epoch. |
zicato propose --output <file> | zicato propose | No --output; it writes experiment.json into the next generation dir itself. |
zicato patch apply --experiment <file> --as vN | (none) | No separate apply step. propose creates the candidate generation and writes its experiment in one shot; tournament / evolve apply patches internally. |
zicato tournament vN vM | zicato tournament PARENT CHILD | Positional generation ids. |
Always confirm with .venv/bin/zicato <cmd> --help before relying on a flag.
The manual round, stage by stage
Z=.venv/bin/zicato
$Z mutations --show preview
$Z analyze-telemetry --round 7
$Z propose
$Z propose --patterns-from path/to/patterns.json
$Z epoch list
sed -n '1,40p' .zicato/epochs/<epoch>/generations/vN+1/experiment.json
$Z tournament v3 v4
$Z tournament v3 v4 --mode fast
$Z tournament v3 v4 --skip-regression
tournament does NOT encode the verdict in its exit code. It prints a JSON
result payload and exits 0 for both promote and reject; a usage/config problem
raises a click.ClickException (exit 1). The fine-grained codes the design
docs describe (6=reject etc.) are not implemented — read the decision in
the printed JSON, do not branch on the exit code for promote-vs-reject.
What each stage leaves on disk (the inspection points)
All paths are under .zicato/epochs/<epoch>/:
insights/round_{N}.md — analyzer output (stage 1).generations/vN/experiment.json — hypothesis (written before scoring) +
patch_ids + the outcome block (written after the tournament).generations/vN/patches/*.json — one file per patch.generations/vN/runs/<entry>/{events.jsonl,loss.json} — per-entry telemetry.journal.md — appended at each promote/reject.
Read these between stages rather than re-running. After any hand-edit of a
canonical file, run zicato reindex so index.db re-derives (see
zicato-index-ops).
When NOT to use this skill
- Normal operation → run
zicato evolve (it orchestrates all of the above and
launches the dashboard; report its URL, default http://127.0.0.1:7892).
- Loop not improving →
zicato-triage-stuck-loop.
- Formulating the pre-run hypothesis →
zicato-design-experiment.
See also
docs/design/CLI.md — full subcommand reference and exit codes.docs/design/EPOCHS-AND-JOURNALING.md — the Experiment artifact + journal.docs/design/SCORING.md — what the tournament gate decides.docs/design/MUTATION-SURFACE.md — what mutations enumerates.- sibling skills:
zicato-index-ops, zicato-design-experiment,
zicato-triage-stuck-loop.
