VianoBugAnalysis/docs/architecture.md

# VianoBugAnalysis – Architektur- und Planungskonzept

*Stand der Planung nach der initialen Vcore-/wowBugAnalysis-Konzeption*


## 1. Zweck und Grundidee

VianoBugAnalysis ist ein autonomes System zur strukturierten Fehleranalyse in Softwareprojekten. Sein Entwicklungsursprung liegt im Vcore-/WoW-Projekt, die Architektur soll jedoch so allgemein gehalten werden, dass dieselben Mechanismen später auch für andere Softwareprojekte genutzt werden können.

Die konkrete WoW-Implementierung trägt den Namen wowBugAnalysis. Sie besteht aus VianoBugAnalysis plus Vcore-/WoW-spezifischen Adaptern, Konfigurationen und Investigation-Tools.

Die zentrale Aufgabe von VianoBugAnalysis lautet:

Eingehende Fehlerdaten werden zu einem vollständigen Case zusammengeführt, semantisch interpretiert, durch mehrere Hypothesen untersucht und am Ende entweder in eine belastbare Diagnose mit technischem Änderungsauftrag oder in eine kontrollierte menschliche Review überführt.

VianoBugAnalysis erzeugt selbst keinen Patch. Es schreibt keinen Sourcecode, verändert keine Datenbank, erstellt keine Git-Branches, startet keinen Build und steuert kein Lab. Seine Systemgrenze endet bei Diagnose und Change Request.


## 2. Einordnung in die geplante Toolchain

Die bisher geplante Toolchain wird in klar getrennte Verantwortungsbereiche zerlegt.

Für Vcore/WoW:

Tester / Bugreport
→ wowdiag
→ wowsrc
→ wowBugAnalysis
→ Change Request
→ allgemeiner Coding-Agent
→ wowValidate
→ LabController
→ wowBugLab
→ Testserver / menschliche Freigabe

Für neue Inhalte ist die Entwicklungsseite getrennt:

Mod-Spezifikation
→ allgemeiner Coding-Agent
→ wowValidate
→ LabController
→ wowDevLab
→ Release Candidate
→ Testserver

Wesentliche Trennung:
- wowDevLab ist die Werkstatt für noch unfertige Inhalte. Frühe Entwicklungsfehler werden dort behoben und nicht in die reguläre Bugpipeline eingespeist.
- wowBugLab behandelt konkrete Fehler in bereits grundsätzlich funktionierendem Inhalt.
- Erst wenn ein Mod im DevLab ausreichend ausgereift ist, gelangt er auf den Testserver. Erst dort gefundene Fehler werden reguläre Bugfälle.

Der allgemeine Coding-Agent soll später sowohl Bugfix-Aufträge als auch Mod-/Feature-Aufträge ausführen können. Der Auftragstyp bestimmt seine Policy, nicht ein separater Agent.


## 3. Zentrale Designprinzipien

3.1 Diagnose statt Patch-Erzeugung
VianoBugAnalysis soll ausdrücklich interpretieren und diagnostizieren. Wo wowdiag nur Daten sammelt und wowsrc Implementierungskontext bereitstellt, darf BugAnalysis Aussagen wie „Das hier ist sehr wahrscheinlich kaputt“ treffen – aber noch keine Änderungen ausführen.

3.2 Deterministische Systeme arbeiten der LLM zu
LLM-Einsatz wird nicht vermieden, sondern auf die Aufgaben konzentriert, für die semantisches Verständnis notwendig ist:
- menschliche Berichte interpretieren
- Soll-/Ist-Abweichungen verstehen
- Hypothesen formulieren
- Evidenz semantisch bewerten
- finale Diagnose formulieren
- technische Änderungsanforderungen ableiten

Deterministische Komponenten übernehmen:
- Paketvalidierung
- Datenextraktion
- Source-/DB-/Log-Abfragen
- Provenienz
- Zustandsverwaltung
- Budgetregeln
- Schema-Validierung
- Dateisystem-/Jobverwaltung

3.3 Kein freier Shellzugriff für eine KI
Die LLM darf nie beliebige Shell- oder SQL-Befehle ausführen. Sie formuliert strukturierte Tool-Requests. Kontrollierte Tools beschaffen die Informationen read-only.

3.4 Menschliche Beobachtungen sind First-Class Data
Testerberichte sind häufig die stärksten semantischen Hinweise auf das tatsächliche Fehlerbild. Direkte Beobachtungen werden daher prominent behandelt. Tester-Hypothesen werden getrennt gespeichert und nur als Hinweise gewertet.

3.5 State lives with the case, not with the service
Das Bugpaket ist die vollständige transportable Fallakte. Der Dienst selbst muss sich einen Bug nicht über Wochen „merken“. Ein zurückkehrender Fall enthält seine komplette Historie, vorherige Diagnosen, Evidenz, Patch-Rückmeldungen und Analyse-Revisionen.

3.6 Append-only
Ein Case-Paket darf durch BugAnalysis nur wachsen. Fachliche Artefakte werden nicht gelöscht oder nach Abschluss überschrieben. Neue Revisionen und neue Evidenz werden hinzugefügt. Index-/Pointerdateien dürfen aktualisiert werden.


## 4. Job-Lifecycle

BugAnalysis verarbeitet Fälle asynchron. Es wartet nach einer Übergabe nicht auf Coding-Agent, Validator oder Lab, sondern nimmt sofort den nächsten offenen Fall.

Hohe Zustände:

NEW
→ VALIDATED
→ BUILDING_CASE
→ INTERPRETING_CASE
→ GENERATING_HYPOTHESES
→ INVESTIGATING_HYPOTHESES
→ BUILDING_DIAGNOSIS
→ OUTPUT_READY
→ HANDED_OFF

Sonderzustände:
- BLOCKED: Die Analyse könnte weitergehen, sobald eine externe Bedingung wieder erfüllt ist, z. B. LLM-Provider oder Research-Service nicht erreichbar.
- FAILED_TO_ANALYZE: Die vorgesehenen Untersuchungsmöglichkeiten wurden ausgeschöpft, ohne eine belastbare Diagnose zu erreichen. Der Fall geht in Human Review.
- REOPENED: Neue Evidenz, Testerfeedback oder ein abgelehnter Patch eröffnet denselben Case erneut als neue Analysis Revision.

Wichtige Regel:
CASE WAITING ≠ WORKER WAITING

Ein Case im Zustand HANDED_OFF oder BLOCKED hält den Worker nicht auf.

Rückläufer:
- Ein Tester lehnt Patch 1 ab.
- BugLab meldet, dass der Fehler weiter besteht.
- Neue Beobachtungen werden ergänzt.
- Der bestehende Case wird wieder geöffnet.
- Die alte Analyse bleibt vollständig erhalten.
- Es entsteht analysis_revision + 1.

FAILED_TO_ANALYZE ist kein endgültiges Ende. Nach menschlicher Review und neuer Evidenz kann derselbe Case erneut geöffnet werden.


## 5. Inbox, Cache, Review und Outbox

Geplante Arbeitsverzeichnisse:

inbox/
- noch nicht validierte eingehende Case-Pakete

quarantine/
- ungültige oder beschädigte Pakete
- zusätzlich validation_error.json

cache/
- unveränderte Originalpakete und temporäre Arbeitskopien

cases/
- persistenter Arbeitszustand während einer aktiven Analyse

outbox/
- erfolgreich analysierte Pakete mit Change Request

review/
- FAILED_TO_ANALYZE-Fälle für menschliche Review

runtime/
- aktueller Workerzustand, z. B. current_job.json

BLOCKED-Fälle können zurück in die Inbox gelegt werden, sollten jedoch mit retry_not_before und Retry-Grund versehen werden, damit ein temporärer Ausfall nicht denselben Fall in einer Endlosschleife priorisiert.


## 6. Case-Paket als langlebige Bugakte

Das zentrale Transportformat ist ein ZIP-basiertes Viano Bug Case Package. Für Vcore/WoW ist ein menschlich gut unterscheidbarer Dateiname vorgesehen, z. B.:

wow-Bug-000011.vbcase.zip

Der Dateiname ist nicht autoritativ. Die Programmlogik darf daraus weder Case-ID, Projekt, Status noch Revision ableiten. Der Einstiegspunkt ist immer manifest.json.

Ein umbenanntes Paket muss weiterhin korrekt funktionieren, solange sein Manifest gültig ist.

Das Paket ist self-contained:
- ursprünglicher Bugreport
- Reproduktionen
- wowdiag
- wowsrc
- CaseBuilder-Ergebnisse
- Recherche
- Hypothesen
- Evidenz
- Investigation-Historie
- Diagnosen
- Change Requests
- spätere Patch-/Lab-Rückmeldungen

Ein Rückläufer nach Tagen oder Wochen besitzt damit dieselbe Qualität wie ein frischer Fall, weil kein externes Gedächtnis vorausgesetzt wird.


## 7. Vorgeschlagene Paketstruktur

Beispiel:

wow-Bug-000011.vbcase.zip
├── manifest.json
├── original/
│   ├── bug_report.json
│   ├── reproductions/
│   ├── wowdiag/
│   └── wowsrc/
├── case/
│   ├── case.json
│   ├── case_summary.md
│   └── details/
├── research/
│   └── R0001/
├── analysis/
│   ├── revisions/
│   │   ├── 0001/
│   │   └── 0002/
│   └── current.json
├── handoffs/
│   └── coding/
│       └── CR-0001/
├── feedback/
│   └── PATCH-0001/
└── history/
    └── events.jsonl

Regeln:
- original/ wird niemals verändert.
- abgeschlossene analysis/revisions/NNNN/ werden niemals verändert.
- neue Reproduktionen, Feedbacks und Revisionen werden hinzugefügt.
- manifest.json und current.json dürfen als Index-/Pointerdateien aktualisiert werden.
- unbekannte Dateien werden niemals gelöscht; sie werden unverändert übernommen.


## 8. manifest.json

manifest.json ist der autoritative Einstiegspunkt für jedes System.

Es enthält mindestens:
- Paketformat und Formatversion
- package_id
- case_id
- Projektprofil, z. B. wow/vcore
- Erstellungs- und Änderungszeit
- aktuellen Routing-/Lifecycle-Status
- aktuelle Analysis Revision
- Zeiger auf aktuelle Case-, Diagnose- und Change-Request-Artefakte
- Zähler/Historienübersicht
- Integritätsinformationen für wichtige Artefakte

Beispielhafte Projektdaten:

project:
  type: wow
  profile: vcore
  display_name: Viano-Core

Das Manifest ist die einzige Quelle, aus der ein Programm Identität und Routing des Pakets ableiten darf.


## 9. Paket-Invarianten

Für v1 werden fünf zentrale Invarianten festgeschrieben:

1. Append-only
Kein abgeschlossenes fachliches Artefakt wird gelöscht oder überschrieben.

2. Self-contained
Ein zurückkehrender Case trägt alles mit, was BugAnalysis für seine bisherige Historie benötigt.

3. Versioned
Paketformat und wichtige JSON-Verträge besitzen Schema-/Formatversionen.

4. Traceable
Jede Diagnose muss auf Evidenz und deren Herkunft zurückführbar sein.

5. Superset
Der Output enthält mindestens alle fachlichen Informationen des Inputs.

Formal:
Files(Input) ⊆ Files(Output)
mit Ausnahme klar definierter aktualisierbarer Indexdateien.

Weitere technische Regeln:
- atomare Paketgenerierung
- ZIP-Slip-Schutz
- Größenlimits
- Deduplizierung/Idempotenz
- Case-Locking
- Hashes für wichtige unveränderliche Artefakte
- keine Secrets in Case-Paketen


## 10. Phase 1 – CaseBuilder

Der CaseBuilder diagnostiziert noch nichts. Er erzeugt aus allen verfügbaren Quellen eine konsistente Fallakte.

Eingaben:
- Bugreport
- Testerbericht
- Testerkommentare
- Reproduktionsdaten
- Reproduction Events
- wowdiag-Paket
- wowsrc-Paket
- Sollzustand / erwartetes Verhalten
- ggf. externe Recherche

Interne Teilaufgaben:
- ReportCollector
- ReproductionCollector
- DiagnosticPackageLoader
- SourceContextLoader
- ExpectedBehaviorResolver
- ExternalResearchProvider
- CaseAssembler

Menschliche Beobachtungen bleiben prominent und werden nicht zu einem anonymen Textblock degradiert.

Direkte Beobachtung, erwartetes Verhalten und Tester-Hypothese werden getrennt.

Der Sollzustand ist Teil des Cases:
- vollständig durch Tester angegeben → übernehmen
- teilweise angegeben → ergänzende Recherche
- fehlt → Recherche

Für Quest-Bugs darf die Netzrecherche ausdrücklich bereits beim Case Building erfolgen. Ziel ist ein belastbarer Soll-/Ist-Vergleich, bevor die Hypothesenphase beginnt.

Externe Recherche beschreibt den vorgesehenen Ablauf, aber niemals die lokale Vcore-Implementierung.


## 11. case.json und case_summary.md

case.json ist die kanonische Maschinenakte des CaseBuilders. Große Rohdaten werden referenziert und nicht vollständig eingebettet.

Vorgesehene Hauptblöcke:
- case
- bug
- human_observations
- expected_behavior
- reproduction
- entities
- runtime_facts
- database_context
- source_context
- research
- data_quality
- inputs

Fakten erhalten IDs wie F0001, F0002 usw. Spätere Hypothesen können auf diese IDs verweisen.

Entities werden normalisiert gespeichert, z. B.:
type = quest
id = 26912
roles = [primary_focus]

Große SmartScript-Mengen, lange Eventlisten und komplette Source-Dateien bleiben außerhalb von case.json und werden referenziert.

case_summary.md wird deterministisch aus case.json erzeugt und dient ausschließlich der Menschenlesbarkeit. Es ist keine zweite Wahrheit und enthält keine zusätzliche Interpretation.


## 12. Phase 2 – Case Interpretation

Phase 2 ist der erste LLM-Schritt.

Aufgabe:
Der vorbereitete Case wird semantisch interpretiert und in eine Richtung strukturiert, ohne eine konkrete Fehlerursache festzulegen.

Die Interpretation darf:
- relevante Bereiche hervorheben
- den ersten bekannten Punkt der Abweichung bestimmen
- Ist und Soll gegenüberstellen
- wichtige Daten/Indizien priorisieren
- Widersprüche und Wissenslücken sichtbar machen

Sie darf nicht:
- eine Root Cause behaupten
- konkrete Fehlerhypothesen als Ergebnis festlegen
- Patchvorschläge erzeugen

Der Zweck besteht darin, Phase 3 bereits mit einem gerichteten, aufbereiteten Suchraum zu versorgen. Ohne diese Vorarbeit müsste die LLM in der Hypothesenphase alle Daten erneut selbst durchsuchen.


## 13. LLMGateway und Prompting

Die LLM ist eine austauschbare Reasoning-Komponente, nicht das Programm selbst.

Architektur:

CaseInterpreter
→ PromptBuilder
→ LLMGateway
→ Provider-Adapter
→ lokaler LLM-Server / eigener Remote-Server / Cloud-Service
→ strukturierte Antwort
→ Schema-Validierung
→ case_interpretation.json

LLMGateway-Aufgaben:
- Providerwahl
- Failover
- Timeout/Retry
- Promptversion
- Output-Schema
- Logging von Modell/Provider
- Token-/Kostenmetrik
- Datenschutzprofile
- lokale Systeme bevorzugen, Cloud optional

Provider sollen über eine einheitliche interne Schnittstelle angesprochen werden. Ein OpenAI-kompatibler HTTP-Adapter ist ein naheliegender erster Adapter, darf aber nicht die interne Architektur bestimmen.

Prompt und Modell sind getrennt. Promptversionen werden als Dateien gepflegt, z. B.:
prompts/case_interpretation_v1.txt

Die LLM erhält keinen freien Shell- oder Datenbankzugriff.


## 14. Output von Phase 2

case_interpretation.json soll unter anderem enthalten:
- observed_behavior
- expected_behavior
- tester_assumptions
- confirmed_technical_facts
- behavior_gap
- first_known_divergence
- failure_stage
- contradictions
- unknowns
- relevant_entities
- investigation_direction
- interpretation_summary

investigation_direction darf beispielsweise auf „post-interaction quest progression“ oder „event activation / spawn phase“ zeigen, aber noch nicht auf eine konkrete Ursache wie „fehlender SmartAI-Eintrag“.

Zusätzlich wird case_interpretation.md deterministisch aus der JSON-Ausgabe erzeugt.


## 15. Phase 3 – Hypothesengenerierung

Phase 3 darf erstmals konkrete Ursachen vermuten.

Aus case.json und case_interpretation.json werden typischerweise 3 bis maximal 5 wirklich unterschiedliche Hypothesen erzeugt.

Gewichtung:
- H1 orientiert sich stark an Testerbeobachtung und erkanntem Fehlerpunkt.
- H2/H3/... sollen bewusst alternative Erklärungen prüfen und dürfen Testerinput schwächer gewichten.
- Redundante Varianten derselben Idee sollen vermieden werden.

Beispiel für sinnvolle Diversität:
- Quest-State-Transition fehlerhaft
- NPC-AI/Script nach Spawn greift nicht
- Phasing/Visibility erzeugt nur scheinbar dasselbe Fehlerbild

Maximale Hypothesenzahl wird über Config begrenzt, z. B.:
max_hypotheses = 5

Die Grenze gilt pro Analysis Revision für insgesamt erzeugte Hypothesen, nicht nur gleichzeitig aktive.


## 16. Phase 3 – Investigation Loop

Jede Hypothese erhält dasselbe Startbudget.

Eine Iteration:

1. Controller baut Investigation Context.
2. LLM erhält:
   - feste Instruktionen
   - Hypothesenstand
   - Budget
   - offene Fragen
   - Ergebnis der vorigen Query
   - beim ersten Durchlauf: kein vorheriges Ergebnis
3. LLM interpretiert das vorige Ergebnis.
4. LLM erzeugt:
   - Controller-Updates
   - genau definierte Investigation-Tool-Requests
5. Antwort wird vollständig validiert.
6. Nur bei gültiger Antwort werden Aktionen ausgeführt.
7. Query-Ergebnis wird gespeichert.
8. deterministische Novelty-/Evidence-Bewertung erfolgt.
9. in der nächsten Iteration erfolgt die semantische LLM-Bewertung.
10. Budget und Status werden aktualisiert.
11. Checkpoint wird geschrieben.

Die LLM darf nie direkt Budget verändern.


## 17. Investigation Tools und Analysis Controller

Zwei klar getrennte Toolgruppen:

Investigation Tools:
- lesen die Außenwelt
- verändern den Case nicht direkt

Beispiele:
- source.find_text
- source.find_symbol
- source.read_context
- source.find_registration
- database.describe
- database.lookup
- database.find_references
- timeline.query
- logs.window
- research.lookup

Analysis Controller:
- verändert ausschließlich den internen Analysezustand

Beispiele:
- evidence.store
- hypothesis.update
- question.resolve
- question.add
- hypothesis.reject
- hypothesis.create
- investigation.note

Die LLM formuliert strukturierte Befehle. Der Controller validiert sie gegen erlaubte Operationen und Werte.

Eine Antwort wird atomar behandelt: Ist ein Teil technisch ungültig, wird die gesamte Antwort verworfen und nicht teilweise ausgeführt.


## 18. Diagnosebudget

Die Budgetwährung ist eine interne abstrakte Größe und hat nichts mit LLM-Tokens zu tun.

Grundregeln:
- jede Investigation-Aktion kostet Budget
- Mindestkosten einer Anfrage > 0
- gute Evidenz kann einen Teil der Kosten zurückerstatten
- keine einzelne erfolgreiche Anfrage darf zu Netto-Budgetgewinn führen

Invariante:
reward < cost

Praktisch:
budget_remaining -= action_cost
budget_remaining += evidence_reward

Der Reward setzt sich aus deterministischen und semantischen Anteilen zusammen:
- deterministische Novelty-Bewertung
- semantische LLM-Bewertung
- ggf. Hypothesenwirkung

Ein voller Reward darf nur zustande kommen, wenn beide Seiten die Evidenz als wertvoll einstufen.

Die LLM liefert nur eine gedeckelte semantische Bewertung. Der BudgetManager berechnet den tatsächlichen Reward.

Zusätzlich:
- duplicate evidence gibt keinen Reward
- wiederholt geringe Informationsgewinne führen zu frühem Abbruch
- terminale Hypothesen werden nicht weiter untersucht

Ende von Phase 3:
Wenn keine untersuchbare Hypothese mehr genügend Budget für die billigste zulässige Aktion besitzt bzw. alle Hypothesen terminal sind, erfolgt die Gesamtauswertung.


## 19. Status von Hypothesen

Vorgesehene Zustände bzw. Bewertungen:
- new
- investigating
- weak
- plausible
- supported
- strongly_supported
- weakened
- rejected
- budget_exhausted
- abandoned_low_information_gain

Confidence soll nicht als scheinpräzise Prozentzahl dargestellt werden. Stattdessen werden qualitative Stufen und konkrete Evidenzreferenzen verwendet.

Eine stark unterstützte Hypothese beendet die Analyse nicht zwangsläufig sofort. Mindestens eine plausible Alternative sollte kurz gegengeprüft werden, um Confirmation Bias zu reduzieren.


## 20. Neue Analysis Revision nach Review oder Patch-Ablehnung

Wenn eine Analyse scheitert oder ein Patch später abgelehnt wird, wird der Fall nicht neu erfunden.

Beispiel:
Revision 1
→ H1 rejected
→ H2 plausible, budget_exhausted
→ H3 weak
→ FAILED_TO_ANALYZE

Human Review ergänzt neue Evidenz.

Revision 2:
Der CaseBuilder verarbeitet alte Historie plus neue Evidenz. Die LLM kann selbst erkennen, dass die frühere H2 weiterhin sinnvoll ist und sie erneut als Hypothese mit vollem Startbudget aufnehmen.

Dafür ist kein spezieller „review mode“ notwendig.

Dasselbe gilt nach Patch-Ablehnung:
- alte Diagnose
- darauf basierender Patch
- Tester-/Lab-Ergebnis
werden zu neuer Evidenz für die nächste Analysis Revision.


## 21. Phase 4 – Finale Diagnose

Phase 4 ist die letzte eigentliche Phase von VianoBugAnalysis.

Teilaufgaben:
4A Final Hypothesis Evaluation
4B Diagnosis Builder
4C Change Request Builder
4D Output Validation

Die Phase entscheidet:
- Welche Hypothese ist ausreichend gestützt?
- Welche Alternativen wurden verworfen oder geschwächt?
- Welche Restunsicherheit besteht?
- Was ist die technische Root Cause?
- Welche Änderung ist erforderlich?
- Was muss nach dem Fix funktionieren?

Wenn keine Hypothese ausreichend belegt ist:
status = inconclusive
→ FAILED_TO_ANALYZE
→ Human Review
→ kein Coding-Auftrag


## 22. diagnosis_result.json

diagnosis_result.json beschreibt, was als Fehlerursache festgestellt wurde und auf welcher Evidenz diese Aussage basiert.

Vorgesehene Inhalte:
- format/version
- case_id
- analysis_revision
- status
- selected_hypothesis
- root_cause.summary
- root_cause.technical_description
- evidence_refs
- confidence
- alternatives
- remaining_uncertainty

Die Diagnose muss vollständig auf bereits gespeicherte Fakten/Evidenz zurückführbar sein.


## 23. change_request.json – Vertrag zum Coding-Agenten

Der Change Request ist die wichtigste Übergabeschnittstelle zum späteren allgemeinen Coding-Agenten.

Er beschreibt nicht die Untersuchung, sondern den technischen Arbeitsauftrag.

Vorgesehene Inhalte:
- task.type = bugfix
- case_id / analysis_revision
- problem summary
- current_behavior
- expected_behavior
- root_cause
- affected_scope
- required_change
- implementation_intent
- implementation_guidance
- constraints
- preserve
- forbidden_changes / do_not_fix_by
- validation_requirements
- project_context_refs
- diagnosis_ref

Für Bugfixes gilt ein fester, deterministischer Policy-Block:

- kleinste praktisch ausreichende Änderung bevorzugen
- keine neuen Features
- kein unnötiges Refactoring
- bestehendes Verhalten außerhalb des diagnostizierten Defekts erhalten
- keine unnötigen Änderungen an fremden Dateien/DB-Zeilen
- keine unbekannten APIs/Schemata/Symbole erfinden
- nur lokal verifizierten Projektkontext verwenden
- bei fehlendem Implementierungskontext fehlende Informationen melden statt raten
- kein Deployment, Neustart oder Produktionszugriff

Die Diagnose-LLM liefert die fallspezifische Änderungsabsicht; die Bugfix-Policy wird nicht jedes Mal kreativ neu erzeugt.


## 24. Allgemeiner Coding-Agent

Der geplante Coding-Agent soll nicht dauerhaft wow-spezifisch sein.

Er bekommt:
- Change Request
- freigegebenen Projektcode-/DB-Kontext
- Task Policy

Tasktypen können später beispielsweise sein:
- bugfix
- feature/mod

Bugfix:
- minimaler Eingriff
- keine neuen Features
- enger Scope
- bestehendes Verhalten erhalten

Feature/Mod:
- neue Funktionalität erlaubt
- größere strukturelle Änderungen möglich
- neue Dateien/Klassen zulässig, wenn gerechtfertigt

Der Coding-Agent muss nicht wissen, wie die Diagnose entstanden ist.


## 25. Technische Robustheit und Wiederaufnahme

runtime/current_job.json enthält nur den groben Workerzustand, z. B.:
- case_id
- analysis_revision
- stage
- started_at
- last_checkpoint_at

Der detaillierte Zustand liegt im Case.

Checkpoints:
- Case gebaut
- Interpretation abgeschlossen
- Hypothesen erzeugt
- einzelne Hypothese abgeschlossen
- Diagnose erstellt
- Output erzeugt

Kritische JSON-Dateien werden atomar geschrieben:
tmp-Datei → flush → rename

Ein Programmabsturz darf höchstens den letzten noch nicht bestätigten Schritt wiederholen, nicht die komplette Analyse.


## 26. BLOCKED und FAILED_TO_ANALYZE

BLOCKED:
- temporäre äußere Bedingung verhindert Weiterarbeit
- Beispiel: LLM-Server nicht erreichbar
- automatischer Retry möglich
- Paket kann nachgeordnet wieder in die Inbox

FAILED_TO_ANALYZE:
- diagnostische Möglichkeiten für diese Revision ausgeschöpft
- kein Coding-Auftrag
- Paket geht in review/
- failure_report.json enthält:
  - Grund
  - Hypothesenendstände
  - Restfragen
  - empfohlene menschliche Aktionen

Neue menschliche Evidenz kann denselben Fall später als neue Analysis Revision wieder öffnen.


## 27. Research und Sollzustand

Expected Behavior Research ist ein eigenständiger Baustein des CaseBuilders.

Bei Vcore/WoW, besonders bei Quest-Bugs:
- menschlicher Sollzustand wird bevorzugt
- unvollständige Angaben werden ergänzt
- fehlende Angaben werden recherchiert

Die Recherche ist technisch ebenfalls nur ein Tool-/API-Aufruf und kann später durch verschiedene Provider implementiert werden.

Alle Research-Ergebnisse behalten Provenienz:
- tester
- external_research
- combined

Externe Quellen dürfen niemals als Beweis für lokale Vcore-Implementierung behandelt werden. Sie dienen nur zur Rekonstruktion des vorgesehenen Verhaltens.


## 28. Vorgeschlagene Modulstruktur

Erste Zielstruktur:

viano-bug-analysis/
├── main.py
├── config/
├── package/
│   ├── validator.py
│   ├── reader.py
│   ├── writer.py
│   └── manifest.py
├── lifecycle/
│   ├── job.py
│   ├── queue.py
│   ├── state.py
│   └── checkpoints.py
├── case/
│   ├── builder.py
│   ├── report_collector.py
│   ├── reproduction_collector.py
│   ├── expected_behavior.py
│   └── summary.py
├── llm/
│   ├── gateway.py
│   ├── provider_base.py
│   ├── openai_compatible.py
│   └── prompts/
├── analysis/
│   ├── interpreter.py
│   ├── hypothesis_builder.py
│   ├── investigator.py
│   ├── evaluator.py
│   ├── diagnosis_builder.py
│   └── change_request_builder.py
├── tools/
│   ├── router.py
│   ├── source_query.py
│   ├── database_query.py
│   ├── timeline_query.py
│   ├── log_query.py
│   └── research.py
├── evidence/
│   ├── store.py
│   └── scoring.py
├── budget/
│   └── manager.py
├── schemas/
└── profiles/
    └── vcore/
        ├── wowdiag_adapter.py
        ├── wowsrc_adapter.py
        ├── db_tools.py
        └── config.yaml

Nicht alle Module müssen anfangs eigene Prozesse sein. Die Trennung ist logisch und kann zunächst innerhalb einer Python-Anwendung umgesetzt werden.


## 29. Empfohlene erste Implementierungsreihenfolge

Da die Architektur nun weitgehend feststeht, sollte nicht zuerst die LLM angebunden werden.

Empfohlene Reihenfolge:

1. PackageValidator
2. PackageReader
3. PackageWriter
4. Manifest-/Schema-Unterstützung
5. Job-/Case-State und Checkpoints
6. CaseBuilder-Grundgerüst
7. Vcore-Adapter für wowdiag/wowsrc
8. ExpectedBehaviorResolver / Research-Schnittstelle
9. LLMGateway
10. Case Interpretation
11. Hypothesis Builder
12. Investigation Tool Router
13. SourceQueryTool / DatabaseQueryTool
14. EvidenceStore und BudgetManager
15. Investigation Loop
16. Diagnosis Builder
17. Change Request Builder
18. End-to-End-Tests mit bekannten Vcore-Fällen

Diese Reihenfolge schafft zuerst das stabile Paket- und Lifecycle-Fundament, bevor autonome LLM-Schleifen darauf aufbauen.


## 30. Teststrategie für die Entwicklung

Bekannte reale Vcore-Fälle sollen als Regressionstests dienen.

Geeignete Referenzfälle:
- BUG-10 Brewfest: komplexer Eventkontext, menschliche Beobachtung, Gebietskontext
- BUG-11 Quest 26912: expliziter Questfokus, fehlendes lokales Arathi-Gebietsskript, ID-Kollisionsproblematik
- später der bekannte Server-Crash-Fall als anspruchsvoller Laufzeit-/Crash-Test

Ziel ist nicht, diese Bugs im Rahmen der Tooltests erneut zu fixen, sondern zu prüfen:
- Wird der Case vollständig gebaut?
- Werden menschliche Hinweise korrekt eingeordnet?
- Bleibt externe Recherche als externe Evidenz markiert?
- Werden Hypothesen sinnvoll diversifiziert?
- Funktioniert Budget/Reward?
- Wird bei Unsicherheit korrekt FAILED_TO_ANALYZE gemeldet?
- Ist ein zurückkehrender Case vollständig wiederaufnehmbar?


## 31. Offene Detailfragen für die Implementierung

Die Architektur ist ausreichend festgelegt. Einige Detailwerte sollen bewusst erst bei der Implementierung bzw. anhand realer Feldtests bestimmt werden:

- exakte Kosten einzelner Investigation-Aktionen
- initial_budget_per_hypothesis
- max_low_information_steps
- konkrete Confidence-Übergangsregeln
- exakte JSON-Schemas und Pflichtfelder
- Retry-/Backoff-Werte
- konkrete Provideradapter
- Umfang der ersten Source-/DB-Tooloperationen
- Kriterien, wann Expected Behavior als ausreichend gilt
- genaue Hash-/Integrity-Strategie
- Größenlimits für Case-Pakete

Diese Punkte verändern nicht die Grundarchitektur.


## 32. Kurzfassung der Systemgrenze

VianoBugAnalysis ist erfolgreich, wenn es aus einem validen Bug-Case-Paket ein angereichertes Case-Paket erzeugt, das entweder:

A) eine nachvollziehbare, evidenzgestützte Diagnose plus Change Request enthält,

B) als BLOCKED kontrolliert zurückgestellt wird,

oder

C) als FAILED_TO_ANALYZE mit vollständigem Untersuchungsbericht an Human Review übergeben wird.

VianoBugAnalysis verändert niemals Projektcode oder Produktionsdaten.

Die wichtigste langfristige Eigenschaft ist:
Jeder Bugfall trägt seine gesamte Historie in seinem Paket selbst mit.