# AGENT.md — Win Diagnostics ## Mission Win Diagnostics collects and analyses Windows diagnostic information. Its pipeline is: Windows system ↓ collect ↓ normalize ↓ analyse ↓ diagnostic.json The structured diagnostic result is the primary output. This project does NOT generate corporate reports or PDFs. --- ## Migration source The existing `WinDiagnostics` repository is the primary migration source. Migrate progressively rather than copying the entire repository. Before migrating a component, determine whether it is: - collection logic; - normalization logic; - generic diagnostic analysis; - historical evidence; - investigation-specific analysis; - report-generation logic. Only the first three belong here. Historical evidence and investigation-specific material will eventually move to `beffroi-reports`. --- ## Responsibilities Win Diagnostics owns: - Windows evidence collection; - event extraction; - normalization; - diagnostic rules; - technical analysis; - evidence correlation; - confidence/severity classification; - machine-readable diagnostic output. --- ## Non-goals Win Diagnostics does NOT own: - PDF generation; - Typst; - corporate branding; - report layout; - historical incident management; - executive summaries; - organisational recommendations. Do not add dependencies on Reportist. --- ## Diagnostic format Define a versioned structured diagnostic format. Prefer JSON for machine-generated output. Conceptually: { "schema_version": 1, "metadata": {}, "system": {}, "collection": {}, "observations": [], "findings": [], "warnings": [] } Findings should preferably contain: id severity confidence title description evidence Adapt this structure where existing diagnostic data requires it. --- ## Evidence Preserve raw evidence wherever practical. A diagnostic conclusion must be traceable back to observations. Do not replace precise machine evidence with prose summaries when the underlying structured information can reasonably be retained. --- ## Schemas Prefer: schemas/diagnostic.schema.json Treat the diagnostic schema as an interface consumed by other tools. Changes to internal collectors should not require downstream changes when the schema remains compatible. --- ## Privacy Example and test fixtures must be sanitized. Avoid committing unnecessarily identifying: - usernames; - hostnames; - serial numbers; - account identifiers; - network identifiers. Real investigation evidence belongs in the appropriate private reporting repository rather than generic fixtures. --- ## Architecture Prefer conceptual separation between: collection normalization analysis schemas Do not force directory boundaries where they make implementation worse. --- ## Testing Maintain sanitized fixtures representing known diagnostic situations. Analysis should be testable against stored fixtures without requiring access to the original machine. Regression tests are particularly valuable for diagnostic rules. --- ## Output The end of a successful diagnostic run should be a documented structured artifact such as: diagnostic.json Human-readable console summaries are useful but are not the canonical integration interface. --- ## Development principles Prefer: - PowerShell for native Windows collection where appropriate; - structured output; - deterministic analysis; - explicit evidence references; - testable rules; - minimal dependencies. Avoid: - parsing presentation-oriented output when structured APIs exist; - report-specific prose; - renderer dependencies; - absolute machine-specific paths. --- ## Definition of success A fresh clone can collect/analyse supported Windows diagnostic information and produce a valid structured diagnostic result without Reportist or any Beffroi reporting repository installed.