3.9 KiB
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.