Add AGENTS.md

This commit is contained in:
Dandaedre 2026-09-15 14:51:21 +02:00
parent b4150997aa
commit 2b07888e8e
1 changed files with 210 additions and 0 deletions

210
AGENTS.md Normal file
View File

@ -0,0 +1,210 @@
# 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.