architecture-triage

Architecture Triage

Autonomt vurder og los arkitekturproblemer som oppdages under testing, uten a stoppe for menneskelig godkjenning med mindre omfanget er stort.

Nar dette gjelder

Bruk denne skillen nar en feil IKKE kan fikses med en enkel kodeendring, men krever:

• Endring av grensesnitt mellom moduler
• Flytting av ansvar mellom komponenter
• Endring av dataflyt eller kontrakter (YAML-skjemaer, filstrukturer)
• Ny abstraksjon eller refaktorering av eksisterende

Nar dette IKKE gjelder

• Vanlige bugs (feil logikk, manglende null-sjekk) — fiks direkte
• Visuelle feil (feil tekst, layout) — fiks direkte
• Ytelsesproblemersom — logg og rapporter etter kjoring

Prosess

Arkitekturproblem oppdaget
  |
  1. Dokumenter problemet
  |     - Hva feilet (teststed, feilmelding)
  |     - Hvorfor en enkel fix ikke holder
  |     - Hvilke moduler/filer er involvert
  |
  2. Vurder omfang
  |     - Tell antall filer som ma endres
  |     - Sjekk om kontrakter mellom moduler endres
  |     - Sjekk CLAUDE.md for relevante konvensjoner
  |
  3. Beslutt handling basert pa omfang
  |
  +-- LITE (1-3 filer, ingen kontraktendringer)
  |     - Fix direkte i koden
  |     - Kjor berort test pa nytt
  |     - Commit med "fix(arch):" prefix
  |     - Fortsett E2E-sekvensen
  |
  +-- MEDIUM (4-10 filer, mindre kontraktendringer)
  |     - Opprett git worktree
  |     - Implementer fix i worktree
  |     - Kjor HELE testsuiten (ikke bare berort test)
  |     - Hvis gront: merge worktree
  |     - Hvis rodt: reverter, dokumenter, flagg for bruker
  |     - Commit med "refactor(arch):" prefix
  |
  +-- STORT (>10 filer, endrer kontrakter mellom moduler)
  |     - IKKE implementer
  |     - Skriv et kort dokument: problem, pavirkning, 2-3 losningsforslag
  |     - Lagre i docs/superpowers/arch-issues/YYYY-MM-DD-<beskrivelse>.md
  |     - Flagg for bruker med sammendrag
  |     - Fortsett E2E med midlertidig workaround hvis mulig

Omfangsvurdering — sjekkliste

For a bestemme LITE / MEDIUM / STORT, svar pa disse:

Sporsmal	LITE	MEDIUM	STORT
Antall filer som endres	1-3	4-10	>10
Endres YAML-skjemaer (vendors.yaml, receipt-status.yaml)?	Nei	Tilleggsfelt OK	Strukturendring
Endres public API/interface?	Nei	Intern refaktor OK	Ekstern kontrakt endres
Pavirker andre moduler som ikke testes na?	Nei	Kanskje 1-2	Ja, flere
Kan endringen reverseres med git revert?	Ja	Ja (worktree)	Komplisert
Bryter det eksisterende unit-tester?	Nei	Noen (oppdateres)	Mange

Tommelregel: Hvis du er i tvil mellom to nivaer, velg det hoyere (sikrere).

Worktree-protokoll (MEDIUM)

# 1. Opprett worktree
git worktree add /tmp/arch-fix-<beskrivelse> -b arch-fix/<beskrivelse>

# 2. Implementer fix i worktree
cd /tmp/arch-fix-<beskrivelse>
# ... rediger filer ...

# 3. Kjor tester
swift test  # eller pytest, avhengig av modul

# 4. Hvis gront: merge
git checkout main
git merge arch-fix/<beskrivelse>
git worktree remove /tmp/arch-fix-<beskrivelse>

# 5. Hvis rodt: reverter
git worktree remove /tmp/arch-fix-<beskrivelse> --force
git branch -D arch-fix/<beskrivelse>

Dokumentasjonsformat (STORT)

# Arkitekturproblem: <kort beskrivelse>

**Oppdaget:** <dato, under hvilken test>
**Omfang:** STORT — <antall filer, moduler>

## Problem
<Hva feilet og hvorfor en enkel fix ikke holder>

## Pavirkning
<Hvilke moduler, kontrakter, og brukere som berores>

## Forslag

### A: <Navn>
- Fordel: ...
- Ulempe: ...
- Estimert omfang: X filer

### B: <Navn>
- Fordel: ...
- Ulempe: ...
- Estimert omfang: X filer

## Anbefaling
<Hvilket forslag og hvorfor>

Logg

Uansett omfang, logg alltid beslutningen:

ARCH-TRIAGE: [LITE|MEDIUM|STORT] — <kort beskrivelse>
  Filer: <liste>
  Beslutning: <fix direkte | worktree | flagget for bruker>
  Begrunnelse: <1 setning>

Denne loggen inkluderes i E2E-rapporten etter fullfort kjoring.