# Upgrade Workflow

The upgrade workflow reads all logs from the session folder and the project's existing rules, applies rule improvements directly, and produces `upgrade.md` — a report of what was changed.

## Inputs

- `session_folder` (required) — should typically contain `logs/` with agent log files.
- `instructions` — optional free-text guidance injected into the artifact builder's prompt.

## Orchestration

The orchestrator (`create_upgrade.py`) is straightforward — it calls the artifact builder once. No loops or sub-agents.

## Agents

**Artifact Builder** (`shared/artifact_builder.py`, stage `upgrade`, model L) — mines session logs and existing rules for generalizable lessons by focusing on concrete signals:

- **Reviewer rejections** — NEEDS_WORK feedback from review agents reveals missing rules.
- **Test failures and fixes** — the diff between what failed and what fixed it reveals patterns worth codifying.
- **User instructions** — explicit guidance passed via `instructions` that sounds general enough to be a rule.
- **Artifact builder self-corrections** — when an artifact builder changes approach mid-response, the corrected approach is the lesson.
- **Repeated patterns** — the same kind of fix or feedback appearing across agents.

Each improvement maps to a specific rule file path (`.mixer/rules/<action>/<module>.md`). The artifact builder edits or creates rule files directly, checks existing rules to avoid duplication, and filters out task-specific details — only general lessons make it through. Writes `upgrade.md` as a report listing every rule file changed and why.
