From 74e877d36a4f564aa906496a49bb1f0775273a5c Mon Sep 17 00:00:00 2001
From: Zio Gabber <78922322+Gabrymi93@users.noreply.github.com>
Date: Thu, 19 Mar 2026 11:36:59 +0000
Subject: [PATCH] docs: clarify rerun workflow

---
 README.md                  |  5 +++++
 docs/advanced-workflows.md | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/README.md b/README.md
index fb3e4b5..7686b54 100644
--- a/README.md
+++ b/README.md
@@ -234,6 +234,11 @@ toolkit run all --config dataset.yml --dry-run --strict-config
 
 `resume`, `profile raw`, `run raw|clean|mart` e la policy completa degli artifacts restano disponibili, ma sono tooling avanzato: vedi [docs/advanced-workflows.md](docs/advanced-workflows.md).
 
+In particolare, [docs/advanced-workflows.md](docs/advanced-workflows.md)
+chiarisce quando restare su `run all`, quando preferire rerun parziali
+(`run clean`, `run mart`, `run cross_year`) e quando usare `resume` senza
+rilanciare l'intera pipeline.
+
 ## Notebook locali
 
 Nei repo dataset clonati dal template, i notebook dovrebbero leggere gli output reali gia` scritti dal toolkit, non ricostruire logica di path.
diff --git a/docs/advanced-workflows.md b/docs/advanced-workflows.md
index 3fd48f2..2ecdf12 100644
--- a/docs/advanced-workflows.md
+++ b/docs/advanced-workflows.md
@@ -15,6 +15,38 @@ Questa categoria include anche tooling di supporto che non va confuso con il run
 - `resume`
 - run parziali per layer
 
+## Quando usare cosa
+
+Regola pratica:
+
+- se stai eseguendo un dataset per la prima volta o hai cambiato fonte, anni,
+  `dataset.yml` o logica `clean.sql`, parti da `toolkit run all`
+- se hai toccato solo SQL `mart`, preferisci `toolkit run mart`
+- se hai aggiunto o modificato solo output multi-anno, preferisci
+  `toolkit run cross_year`
+- se un run si interrompe ma il run record e gli artefatti precedenti sono
+  ancora coerenti, usa `toolkit resume`
+- se hai toccato solo notebook, docs o script locali del repo dataset, non
+  rilanciare la pipeline per default
+
+Matrice minima:
+
+| Tipo di modifica | Comando consigliato |
+|---|---|
+| prima esecuzione del dataset | `toolkit run all --config dataset.yml` |
+| cambio fonte o perimetro anni | `toolkit run all --config dataset.yml` |
+| cambio `dataset.yml` con impatto su input/layer | `toolkit run all --config dataset.yml` |
+| cambio `clean.sql` | `toolkit run clean --config dataset.yml` poi `toolkit run mart --config dataset.yml` |
+| cambio solo `mart.sql` | `toolkit run mart --config dataset.yml` |
+| cambio solo `cross_year` | `toolkit run cross_year --config dataset.yml` |
+| run interrotto a meta' | `toolkit resume ... --config dataset.yml` |
+| cambio solo notebook/docs | nessun rerun automatico |
+
+Il toolkit non impone di cancellare `raw/`, `clean/`, `mart/` o `cross/` tra un
+run e l'altro. Negli ambienti di lavoro questi output possono restare come
+cache locale finche' il loro perimetro e' ancora coerente con la config e con
+il layer che stai rieseguendo.
+
 ## Step singoli
 
 Utili per debug o per ripetere solo una parte della pipeline: