docs: skills simuler and forbedre, README, changelog and contribution guide

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

skills/simuler/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: simuler
+description: "Kjører modellens simuleringer i notatet Den dynamiske rettsstaten med egne forutsetninger: fra et spørsmål («hva om …») til en scenariofil, en kjøring, en tabell med nøkkeltall og tilbud om figur. Dekker styringen (forsinkelse, reaktivitet, MPC), parameterne, beslutningsreglene for påtale og budsjett, sjokk, tiltak (andel ledet utenom, mer kapasitet i domstolen) og sveip over én eller to parametere, og gjenskaper notatets figurer. Bruk når noen vil prøve modellen med andre forutsetninger, sammenligne regler eller tiltak, se hvor grensen for svingninger går, eller lage notatets figurer på nytt. Utløses av «hva om forsinkelsen er seks måneder», «kjør et scenario», «simuler», «sammenlign reglene», «sveip over», «hva skjer med et større sjokk», «lag figuren i notatet på nytt», «run a scenario», «simulate the model with other assumptions»."
+---
+
+# Kjør modellen med egne forutsetninger
+
+Ferdigheten går fra et spørsmål om modellen til en kjøring: hva om forsinkelsen er lengre, sjokket større, kapasiteten
+kommer tidligere eller beslutningsreglene er andre? Den skriver spørsmålet som en scenariofil, kjører modellens
+simuleringer i notatet *Den dynamiske rettsstaten* (avsnitt 8) med kjernens kode uendret, og viser nøkkeltallene.
+Den trenger Python 3 med numpy og scipy.
+
+Brukeren kan være forsker eller arbeide i straffesakskjeden. Snakk vanlig norsk. Nevn ikke filnavn, kommandoer,
+feltnavn eller JSON med mindre brukeren spør etter dem, eller viser at de kjenner dem.
+
+## Regler
+
+- **Finn aldri på et tall.** Forutsetningene er brukerens eller notatets. Alt scenariofila ikke setter, er notatets
+  verdier; si hvilke som er brukt når det betyr noe for svaret.
+- **Vis scenarioet med ord, og få et ja før du kjører.**
+- **Gjengi skriptets tall ordrett.** Regn aldri om, avrund aldri annerledes og «forbedre» aldri et tall. Vil brukeren
+  vite hva som skjer med andre forutsetninger, endrer du scenarioet og kjører på nytt.
+- **Si hver gang** at parameterne er notatets stiliserte verdier, ikke kalibrert på norske data, og at kjøringene
+  viser modellens dynamikk, ikke prognoser.
+- **Installer aldri noe uten å spørre.** Det gjelder også et bibliotek for figurer.
+
+## 1. Finn ut hva som skal sammenlignes
+
+Spør hva brukeren vil vite, med vanlige ord: hva skal endres, hva skal det sammenlignes med, og hva vil brukeren se
+på (kriminalitet, tillit, saksbehandlingstid, kø, kapasitet, andel ledet utenom, politiets innsats)? Ett spørsmål om
+gangen.
+
+Oversett så spørsmålet til modellen. Les `${CLAUDE_PLUGIN_ROOT}/docs/scenarioformat.md` før du skriver en scenariofil
+første gang: den sier hvilken simulator som dekker hva, hvilke felt og parametere som finnes, hva som er tillatt, og
+hvordan sveip virker. For hva en parameter betyr, hvilken ligning den står i og notatets verdi, les
+`${CLAUDE_PLUGIN_ROOT}/docs/modellkart.md`. Gjengi ikke dokumentene for brukeren; bruk dem til å velge.
+
+Et sveip er ofte det brukeren egentlig spør om: «hva om forsinkelsen er 3, 6 eller 11 måneder» er én kjøring med tre
+verdier, side om side. To parametere gir et rutenett.
+
+**Utgangspunkter som følger med.** Tilby dem når de passer, og si hva de er. De ligger i
+`${CLAUDE_PLUGIN_ROOT}/eksempler/scenarioer/`:
+
+| Fil | Spørsmål |
+|---|---|
+| `avviklingstid_koordinert.json` | hvor raskt bør restansen avvikles i den koordinerte regelen (fra 6 til 96 måneder og aldri)? |
+| `stabilitet_reaktivitet_forsinkelse.json` | hvor går grensen for svingninger, over reaktivitet og forsinkelse? |
+| `sjokkstorrelse_kjede.json` | hvor mye betyr størrelsen på sjokket når domstolen er en flaskehals? |
+| `kvalitetssloyfe.json` | hva gjør kvalitetssløyfen med desentraliserte og koordinerte regler? |
+| `utvidelse_bolge.json` | hva etterlater en forbigående bølge i kriminalitetspresset, med og uten flaskehals? |
+
+I undermappa `notatet/` ligger 21 scenariofiler som til sammen lager 20 av notatets 22 datafiler på nytt, det
+figurene i notatet tegnes fra (regimene i figur 4, scenario 1–5 med domstolen, robusthet, vippepunkt og de endogene
+reglene; de to siste datafilene er regnet analytisk, ikke simulert). Med dem kan brukeren se nøyaktig hvilke
+forutsetninger en figur i notatet bygger på, og endre én av dem. Tabellen i `docs/scenarioformat.md`
+(«Eksempelfilene») sier hvilken fil som gir hvilken av notatets datafiler.
+
+Eksemplene kjøres direkte fra pluginen. Skal et eksempel endres, kopierer du det til brukerens arbeidsmappe først og
+gir kopien et nytt navn.
+
+## 2. Vis scenarioet og få et ja
+
+Beskriv scenarioet med ord før du kjører:
+
+- **Hva som varieres**, med verdiene (for eksempel «forsinkelsen i politiets styring: 3, 6 og 11 måneder»).
+- **Hva som holdes fast**: modellen (for eksempel «domstolen som ledd med kø, avsnitt 8.2»), og hva som er notatets
+  verdier (styring, sjokk, parametere, regel).
+- **Over hvor mange måneder**, og hvor mange kjøringer det blir.
+
+Spør: «Skal jeg kjøre dette?» Kjør ikke før brukeren har sagt ja.
+
+## 3. Skriv scenariofila
+
+Skriv scenarioet som en JSON-fil i brukerens arbeidsmappe, med et kort `navn` uten mellomrom og en `beskrivelse` som
+sier spørsmålet med vanlige ord (den står øverst i sammendraget). Feltnavnene skrives nøyaktig som i
+`docs/scenarioformat.md`. Finnes fila fra før, spør før du overskriver den. Gi en ny variant et nytt `navn`, så
+resultatet fra forrige kjøring blir stående.
+
+## 4. Kjør
+
+```
+python3 "${CLAUDE_PLUGIN_ROOT}/modell/kjor.py" --data "${CLAUDE_PLUGIN_DATA}" scenario <fil> --ut <mappe>
+```
+
+- På Windows heter tolken `python`.
+- `<fil>` er hele stien til scenariofila. `<mappe>` er `resultater/<navn>` i brukerens arbeidsmappe, med hele stien.
+  Finnes mappa med et tidligere resultat av samme scenario, erstattes det. Finnes den med andre filer, stopper
+  kjøreren uten å skrive noe.
+- Har brukerens arbeidsmappe en egen arbeidskopi av modellen (mappa `rettsstat-modell/` med `modell/kjor.py` inni),
+  legger du til `--modell <hele stien til rettsstat-modell/modell>` før `scenario`, og sier til brukeren: «Jeg bruker
+  din egen versjon av modellen i rettsstat-modell.» Bruk ellers pluginens modell.
+- Et scenario med noen få kjøringer tar noen sekunder. MPC er tregt (om lag 7 sekunder per kjøring), og et rutenett
+  med mange kjøringer tar tilsvarende lenger.
+
+Exit-koder:
+- **0**: kjøringen er gjort. Gå til trinn 5.
+- **3**: numpy eller scipy mangler. Si i én setning: «Simuleringene trenger to vanlige regnebiblioteker for Python,
+  numpy og scipy. Skal jeg installere dem i en egen mappe for denne pluginen?» Installer bare hvis svaret er ja:
+
+  ```
+  python3 "${CLAUDE_PLUGIN_ROOT}/modell/kjor.py" --data "${CLAUDE_PLUGIN_DATA}" miljo --opprett
+  ```
+
+  Gjengi det kommandoen sier (blant annet om resultatene da kontrolleres bit for bit eller med toleranse), og kjør på
+  nytt. Feiler installasjonen, gjengi meldingen og si at diagnosen fortsatt kan brukes uten tilleggene.
+- **2**: skriptet har stoppet med en melding. Les den:
+  - *Feil i scenariofila …*: meldingen nevner feltet og de gyldige verdiene, og foreslår det nærmeste ved en
+    skrivefeil. Gjengi den med vanlige ord, rett fila, vis endringen og kjør på nytt. Er det brukerens forutsetning
+    som ikke er tillatt (for eksempel en andel over 1), spør hva som var ment.
+  - *… er ikke gyldig JSON*: rett fila og kjør på nytt.
+  - *Kjøringen … stoppet i kjernen*: kombinasjonen av forutsetninger gir ingen likevekt ved start eller en løsning
+    som vokser over alle grenser. Si det med vanlige ord, og hvilken kjøring det gjaldt. Ingenting er skrevet. Endre
+    aldri en forutsetning bare for at kjøringen skal gå; spør brukeren.
+  - *--ut: mappa … finnes og har filer …*: velg en annen mappe og si hvilken.
+  - *Uventet feil i …*: en feil i koden, ikke i scenarioet. Gjengi meldingen og si at kjøringen ikke ble gjort.
+- **Annen kode, eller `python3` finnes ikke**: gjengi meldingen og si at kjøringen ikke ble gjort. Gjett ikke på et
+  svar.
+
+## 5. Presenter svaret
+
+1. **Vis nøkkeltallene slik skriptet skrev dem.** Kjøreren skriver sammendraget til skjermen og til `sammendrag.md`.
+   Vis tabellen (eller tabellene) under «Nøkkeltall» uendret, med linja «Slik leses tallene» under, og for
+   beslutningsreglene budsjettvedtakene. Ikke avrund, regn om eller formater tallene på nytt, og ta ikke bort rader.
+   Er tabellen svært stor, vis radene brukeren spurte om, og si hvor resten står.
+2. **Les den med vanlige ord**, kort: hva endringen gjør i modellen, i hvilken retning og hvor mye, med skriptets
+   tall. Pek på det som er verdt å se: høyeste mot slutt (har forløpet funnet en ny balanse?), vedvarende svingning
+   (spennet de siste 60 månedene), saksbehandlingstid og tillit, og kapasitet og andel ledet utenom der de endres.
+   Si ikke mer enn tallene viser.
+3. **Forbehold** som alltid tas med:
+   - Parameterne er notatets stiliserte verdier (tabell 3 i notatet), ikke kalibrert på norske data, unntatt det
+     scenarioet setter selv. Kjøringene viser modellens dynamikk, ikke prognoser. Rekkefølgen og retningen er
+     poenget, ikke nivåene.
+   - Kø, strøm og kapasitet er i modellens normaliserte enheter, ikke saker eller årsverk. 1,00 er nivået før
+     sjokket.
+   - Bare ett ledd har kø i modellen (domstolen); politi, påtale og kriminalomsorg har ikke kø.
+
+   Ta i tillegg med det som gjelder dette scenarioet, fra `${CLAUDE_PLUGIN_ROOT}/docs/forbehold.md` (for eksempel at
+   beslutningsreglene er stiliserte, eller at andelen som kan ledes utenom er et rettspolitisk valg).
+4. **Si hvor filene ligger**: sammendraget, én CSV-fil per kjøring (én rad per måned) og `resultat.json` med alle
+   parametere slik de ble brukt, versjonene og sjekksummene. Samme scenariofil gir samme filer, så kjøringen kan
+   etterprøves.
+
+## 6. Tilby en figur
+
+Spør: «Vil du se dette som en figur?» Lag den bare hvis svaret er ja.
+
+- **Bruk tallene kjøringen skrev**, uendret: CSV-filene i resultatmappa (med `"format": "notat"` er det `.dat`-filer,
+  med mellomrom mellom feltene). Regn ikke ut nye størrelser for figuren, og glatt ikke kurvene.
+- **Lag figuren slik miljøet tillater** uten å installere noe: med et plottebibliotek som allerede finnes, eller som
+  en tegning du lager selv (for eksempel SVG eller en HTML-side). Mangler alt, spør før du installerer noe.
+- **Én kurve per kjøring**, med kjøringens navn fra sammendraget i forklaringen (for eksempel «forsinkelse=6»).
+- **Aksene på norsk**: «Tid (måneder)» og størrelsen, for eksempel «Kriminalitet K», «Tillit», «Politiets innsats
+  T», «Saksbehandlingstid i domstolen (måneder)», «Kapasitet (1,00 = ved start)» eller «Andel til domstolen». Hva
+  kolonnene betyr, står i `docs/scenarioformat.md` («Tidsseriene per modell»).
+- **Ta med linja om hva 1,00 betyr** under figuren, som i sammendraget: «1,00 er nivået i referanselikevekten før
+  sjokket for kriminaliteten K og politiets innsats T; tilliten er 0,80 der. Kapasitet: 1,00 er kapasiteten ved
+  start.» Skriv i tillegg at tallene er modellens stiliserte dynamikk, ikke prognoser.
+- Lagre figuren i resultatmappa og si hvor den ligger.
+
+## Hva scenariokjøreren ikke gjør
+
+Si det rett ut når spørsmålet ligger utenfor:
+
+- **Egne tall i saker per måned** (innstrømning, kapasitet og restanse per ledd) hører hjemme i ferdighetene
+  `diagnose` (leddet som binder) og `forlop` (forløpet måned for måned med tallene dine). Scenariokjøreren bruker
+  modellens normaliserte størrelser.
+- **En mekanisme modellen ikke har** (for eksempel kø i flere ledd, målestøy, forskyvning mellom kategorier) kan
+  ikke settes inn med en parameter. Den legges til som en utvidelse; det er ferdigheten `forbedre`.
+- **Endrer scenarioet** `P.gamma`, `P.Lam0` eller `P.T0`, regnes domstolens kapasitet og behandlingstid ikke om, og
+  domstolen er da ikke lenger 95 % utnyttet før sjokket. Si det, og oppgi dem selv hvis brukeren vil ha det (se
+  `docs/scenarioformat.md`).
+- Ingen kjøring kalibrerer modellen mot norske tidsserier eller lager prognoser.
+
+## 7. Neste steg
+
+Tilby det som passer:
+- en variant med én forutsetning endret, kjørt med nytt navn og vist ved siden av den første, med skriptets tall;
+- et sveip over forutsetningen brukeren er mest usikker på;
+- notatets scenariofil for samme figur, for å se forskjellen mot notatets forutsetninger;
+- ferdigheten `forbedre`, hvis spørsmålet krever en mekanisme modellen ikke har.