docs: clarify rerun and resume decision rules

README.md

@@ -303,6 +303,25 @@ 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.
 
+### Decision Rule Rapida
+
+Se non sei sicuro, parti da questa regola minima:
+
+| Se hai cambiato... | Comando consigliato |
+| --- | --- |
+| fonte, anni, extractor o shape di `dataset.yml` | `toolkit run all --config dataset.yml` |
+| logica `clean.sql` o `clean.read` | `toolkit run clean --config dataset.yml` poi `toolkit run mart --config dataset.yml` |
+| solo SQL `mart` | `toolkit run mart --config dataset.yml` |
+| solo output `cross_year` | `toolkit run cross_year --config dataset.yml` |
+| solo notebook, docs o note metodologiche | nessun rerun automatico |
+| run interrotto con artefatti precedenti coerenti | `toolkit resume ... --config dataset.yml` |
+
+Regola pratica:
+
+- `run all` resta il percorso canonico
+- i rerun parziali servono per non rilanciare tutto quando il perimetro del cambio e' gia' chiaro
+- `raw`, `clean`, `mart` e `cross_year` locali possono restare come cache di lavoro: non vanno cancellati a caso tra un test e l'altro
+
 ## Notebook locali
 
 Nei repo dataset clonati dal template, i notebook dovrebbero leggere gli output reali gia` scritti dal toolkit, non ricostruire logica di path.

docs/advanced-workflows.md

@@ -19,8 +19,11 @@ Questa categoria include anche tooling di supporto che non va confuso con il run
 
 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 stai eseguendo un dataset per la prima volta, parti da `toolkit run all`
+- se hai cambiato fonte, anni, extractor, `dataset.yml` o il perimetro del RAW,
+  torna a `toolkit run all`
+- se hai cambiato `clean.sql` o la logica `clean.read`, riparti da
+  `toolkit run clean` e poi `toolkit run mart`
 - se hai toccato solo SQL `mart`, preferisci `toolkit run mart`
 - se hai aggiunto o modificato solo output multi-anno, preferisci
   `toolkit run cross_year`
@@ -36,17 +39,24 @@ Matrice minima:
 | 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 `clean.sql` o `clean.read` | `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` |
+| run interrotto a meta' con run record/artifacts coerenti | `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.
 
+In pratica:
+
+- non trattare `run all` come default per ogni modifica minima
+- non cancellare gli output locali "per pulizia" se non hai cambiato il loro perimetro
+- usa i rerun parziali quando il punto di ingresso corretto e' chiaro
+- usa `resume` per recovery, non come scorciatoia generica a meta' sviluppo
+
 ## Step singoli
 
 Utili per debug o per ripetere solo una parte della pipeline: