20 KiB
Diagnostics reports
diagnostics.typ generates a synthetic Windows health assessment from the structured JSON
report produced by windiagnostics/WindowsMaintenanceReport.ps1.
Quick start
Collect a Full report on Windows, copy the resulting .json file into
diagnostics/, then run from this repository:
./render-diagnostics.sh diagnostics/windows_system_report_PC.json "Your Name"
The theme is optional and defaults to default.
Choose a theme with the optional third argument:
./render-diagnostics.sh diagnostics/windows_system_report_PC.json "Your Name" eridani
Render every .json dump under diagnostics/ recursively:
./render-diagnostics.sh --all "Your Name"
Select a non-default theme for the complete batch:
./render-diagnostics.sh --all "Your Name" cic
Nested source directories are reproduced under build/diagnostics/, preventing
reports with identical filenames from overwriting one another.
The command creates:
build/diagnostics/windows_system_report_PC.pdf
The author is mandatory. The diagnostic date comes from the report's generated_at field and is also mandatory. Missing values stop compilation with an explicit
message.
Pipeline
modules/diagnostics-normalize.typreads WinDiagnostics schema versions 1 and 2 JSON, deduplicates event records, classifies signals, and builds normalized data entirely inside Typst.diagnostics.typvalidates the inputs and selected YAML theme.modules/diagnostics-model.typrenders the final PDF and uses PrimaViz for the summary visualization.
No Python conversion or external normalization step is required for native captures. Typst reads
the .json dump directly. It downloads @preview/primaviz:0.10.0 on the first
build and caches it locally.
The normalizer also correlates CatRoot2 checksum errors with CryptSvc crashes in ESENT.dll and Windows Update failures within two minutes of a checksum event. When all three signals are present, the generated PDF includes a priority finding and a shared investigation plan. Individual events remain visible; the correlation adds no extra health-score penalty. This identifies a related failure sequence, not a proven hardware root cause. Disabled display adapters receive Code 22 guidance, and non-elevated captures receive a coverage warning.
Run the parser and correlation regression checks with:
typst compile --root . tools/check-diagnostics.typ /tmp/check-diagnostics.pdf
Report structure
The document is divided into three purposeful parts:
- Executive overview — the short first-page health assessment, capacity metrics, heuristic health graph, priority findings, and signal chart.
- Findings requiring attention — a resolution plan for every actionable exception, followed by its correlated, deduplicated event evidence.
- Technical evidence — system context, storage capacity, inventory counts, selected source output, and collector-coverage audit.
The executive overview is deliberately short:
- overall assessment;
- critical and warning counts;
- a health score and aggregate analysis confidence;
- maximum installed memory and aggregate analysis confidence;
- the four highest-priority findings;
- a compact free-space chart for every captured volume.
The remaining two parts contain:
- system and storage profile;
- inventory counts instead of full healthy inventories;
- all actionable findings;
- deduplicated event-log evidence;
- selected source evidence for hardware, storage, security, networking, power, DISM, and SFC;
- a collector-coverage table describing how every source section was used.
Noise and privacy policy
The report favors exceptions over exhaustive reproduction:
- repeated identical event records are collapsed and counted;
- related event variants share one top-level finding;
- installed applications, Store packages, services, drivers, tasks, startup entries, and listeners are counted rather than listed in full;
- SFC progress lines are removed while its final result is retained;
- raw IP configuration, user paths, and other noise-heavy or sensitive values are reviewed but not reproduced;
- healthy status remains visible in relevant summaries but does not create an individual finding.
Routine evidence is conditional:
- vanilla enabled firewall profiles are omitted;
- Defender details are omitted when all collected protection flags are true;
- component-store output is omitted when it contains no repairable, corruption, or error signal;
- battery output is omitted when WMI reports
OKand at least 20% charge; - DNS servers, power-plan details, and stopped automatic-service snapshots are omitted from evidence but remain accounted for in collector coverage;
- SFC integrity failures are retained and highlighted as critical.
Upgradeable event heuristics
Event interpretation lives in config/diagnostics-rules.yaml, separate from the Typst
parser and layout. Each rule matches an exact provider and event ID and defines
its severity, rationale, and a heuristic confidence estimate:
event_rules:
- provider: "Service Control Manager"
id: "7000"
severity: "warning"
confidence: 90
rationale: "A configured service or driver failed to start."
If no rule matches, the event is retained as unanalysed and visibly labelled
FAIL TO ANALYSE. Add or revise a rule, then rerun the same render command; no
Typst code change is required.
Rules can also provide resolution_steps, reference_url, and
reference_label. The Resolution plan prints numbered steps and an optional
clickable authoritative reference beside the corresponding problem. The older
remediation string remains a supported fallback. Built-in DISM, SFC, firewall,
and device findings provide the same guidance even though they do not originate
from an event rule.
Confidence percentages are review-priority estimates attached to each
classification, not measured failure probabilities. Unknown event rules receive
20% confidence and remain labelled FAIL TO ANALYSE. The overview confidence is
the arithmetic mean of displayed finding confidence values.
The health graph is deliberately simple and reproducible: it begins at 100,
subtracts 8 points per critical finding, 2 per warning, and 1 per unanalysed
signal, then clamps the result to 0–100. Change those weights in
modules/diagnostics-normalize.typ if operational experience calls for different
priorities.
Closing findings safely
“Clear” means proving that the underlying condition is resolved and producing a new diagnostic capture. It does not mean deleting evidence from Event Viewer.
Use this workflow for each item in the PDF's Resolution plan:
- Save the original PDF and JSON capture if the issue may need escalation or an audit trail.
- Follow the finding's numbered Resolution path. Use its linked vendor or Microsoft guidance when one is provided.
- Perform the stated verification before considering the issue closed. A command completing without an error is not sufficient if the affected service, application, update, backup, or device still fails.
- Reboot when the repair changes system files, drivers, services, firmware, or pending installer state.
- Reproduce the original workload where practical, then run WinDiagnostics again and compile the new dump.
- Compare the new report with the saved report. Close a finding only when its current-state check is healthy or the triggering behavior no longer recurs.
Typical closure checks:
| Finding | What proves it is cleared |
|---|---|
| DISM / component store | /RestoreHealth succeeds and a new health check reports no component-store corruption. |
| SFC integrity | sfc /scannow completes and reports no remaining integrity violations. |
| Firewall | Domain, Private, and Public profiles are enabled, unless a documented organization policy intentionally differs. |
| Service failure | The owning software or driver is repaired, the service starts or stops normally, and the event does not recur after a relevant reboot or test. |
| Application crash or hang | The repaired or updated application completes the previously failing workflow without a matching new event. |
| Windows Update / MSI | The named update or product installation completes successfully and is shown as installed. |
| VSS / Volsnap | vssadmin list writers shows stable writers and a new backup or shadow copy succeeds. |
| Device problem | Device Manager and the next diagnostic capture report the device as healthy. |
| Unexpected shutdown | Record the known cause if intentional; otherwise investigate correlated power, bug-check, thermal, driver, and hardware evidence before closure. |
| Unknown event | Review the raw provider, ID, and message; add a defensible rule and rerun the report. |
Historical events can remain visible after a successful repair because they describe what happened during the collector's look-back window. Leave them intact. A resolved event finding will age naturally and eventually leave future captures; eligible findings may also receive the limited score fading described below. If a clean post-repair capture is needed for handoff, wait until the collector window has advanced rather than clearing the Windows logs.
Age fading
Selected event rules may set fading: true. Their health-score penalty remains
at full value for seven days, then decreases linearly until it reaches 50% at
90 days. It never falls below 50%; the finding, severity, evidence, and
resolution path remain in the report. A faded finding shows its age-adjusted
weight beside the finding text.
Age is measured from the event timestamp to the diagnostic report date in the
report's generated_at field. It never uses the current date or the date on which
the PDF happens to be compiled. If either date cannot be parsed, full weight is
retained.
Fading is enabled only for events expected to re-log on recurrence or whose old instance becomes less useful with time: service start/stop failures, application crashes and hangs, Windows Update failures, and installer failures. It is deliberately disabled for storage-controller errors, TPM attestation, firewall, SFC/DISM, VSS/Volsnap, NDIS power transitions, unexpected shutdowns, devices, and unknown events. Those signals may be persistent, intermittent, or unsafe to treat as resolved merely because no newer event was captured.
The defaults can be overridden per safe rule with fade_after_days and
fade_to_half_days in config/diagnostics-rules.yaml.
A DISM result of repairable is classified as a warning, not a critical
finding. Microsoft distinguishes it from a non-repairable image and provides
/RestoreHealth as its normal repair path. System-file integrity violations,
TPM pre-attestation failures, and incomplete firewall protection retain their
higher operational priority.
Do not clear Windows event logs merely to make a diagnostic report look clean. An event is historical evidence, not a live alarm. Resolve its cause, perform the stated verification, and rerun WinDiagnostics; old entries naturally leave the report once they fall outside its configured event-history window. Preserve logs needed for incident investigation or audit.
The current rules use conservative interpretations of Windows collector data.
For example, Microsoft documents Event 7000 as a service-start failure,
Get-MpComputerStatus boolean fields as protection-state indicators, and
Win32_Battery.EstimatedChargeRemaining as remaining charge percentage. Links
to those references are kept here for future rule maintenance:
- Service Control Manager Event 7000
- Microsoft Defender status fields
- Win32_Battery fields
- DISM and SFC repair sequence
- Enable Windows Firewall profiles
The final coverage table prevents silent omission: every section emitted by the collector is listed with its treatment. False positives remain possible because classification is heuristic; the PDF says so explicitly.
Direct Typst usage
The JSON capture is passed directly to Typst:
typst compile \
--input diagnostics=diagnostics/windows_system_report_PC.json \
--input author="Your Name" \
--input theme=cic \
diagnostics.typ \
build/diagnostics/report.pdf
Available themes are default, cic, and eridani and are defined in
config/themes.yaml.
Input expectations
The parser is designed for Compact, Mid, and Full WinDiagnostics JSON captures, but Full provides the evidence needed for meaningful fault synthesis. Unknown future sections remain listed in coverage as retained in the source without specific analysis.
JSON migration and converted captures
The schema follows WindowsMaintenanceReport.ps1.
The renderer validates report_type, schema_version, and generated_at.
Full/Mid captures use section envelopes (status, count, data, error);
Compact captures use summary and may include metadata-only check sections. Collector warnings and skipped/error/unavailable sections
remain visible. Coverage counts are records, not transcript lines.
Native PowerShell dates may use /Date(milliseconds)/; ISO timestamps and their
offsets are also supported for event correlation. Firewall Enabled accepts
JSON true and the collector's numeric enum value 1. DISM/SFC output remains
text inside JSON; progress lines are removed before displaying evidence.
The existing hardware-* captures were converted with a lossy converter. It
changed CIM keys to snake_case, split event-message fields, and mistook table
separators for section headings. Several inventories contain only headers,
storage volumes are missing, and an empty section name contains displaced data.
These source files are preserved. The renderer accepts recoverable field aliases,
retains extra event-message fields, and reads command conclusions from
legacy_raw. Header-only inventory counts display Unavailable; unparsed
device/firewall tables do not produce false device or disabled-firewall findings.
Every converted report receives an explicit incomplete-evidence finding.
Legacy local event timestamps are left unchanged without age fading or temporal
correlation because their date order/timezone is not established reliably.
Recollect native Full JSON to replace the missing evidence; the renderer cannot
reconstruct lost table rows reliably from these JSON files.
Native event timestamps display as YYYY-MM-DD HH:MM:SS UTC, with raw timestamps
preserved internally for correlation and fading. WER-SystemErrorReporting 1001
is a critical kernel-crash finding; code 0x133 is identified as
DPC_WATCHDOG_VIOLATION.
The saved dump must be analyzed to identify the responsible component.
volmgr 162 records successful dump generation and is informational, so it
adds no health-score penalty and remains visible in the event evidence without becoming an actionable finding.
Schema 2 and partial collection
Both schema versions support Compact, Mid and Full. Unversioned and unsupported
versions are rejected. The September 15 12:10:57 native capture uses schema 2 and is covered by regression checks alongside the earlier schema 1 captures. The fixtures in tools/fixtures additionally cover synthetic edge cases.
New event keys take precedence over legacy aliases, including when unavailable. Groups retain log, provider, ID, Windows numeric level, occurrence counts and raw records. Windows level totals are separate from curated diagnostic severity. Code Integrity information/verbose records are retained without automatically becoming faults. Coverage reports explicit truncation metadata; a count at the limit alone does not establish truncation. The requested history comes from the capture parameters.
Failed, skipped, missing and unknown collection states are not successful checks.
Nested storage and Defender failures remain visible even when the parent succeeded.
Compact and incomplete captures cap analysis confidence at 50%; the heuristic
score describes observed signals only and cannot certify uncollected checks.
Top-level diagnostic_collection booleans are retained as collection metadata,
not health conclusions.
Driver, service, storage, filter, boot, feature, reliability and dump inventories have source-attributed evidence summaries. Expanded sections show at most three records and 1,200 characters, with explicit display limits and full evidence in the source JSON (also retained in the normalized model). Native exit metadata and localized output are kept as data. Inventory presence, stopped services and dump metadata do not establish a cause or constitute dump analysis. Storage sources are kept separate rather than joined by array position.
Absent sections are omitted from inventory and evidence displays and listed only in the final coverage recap as “Not supplied in this capture / Unavailable”. Their absence alone does not add a finding or trigger the partial-collection banner. Explicit failed/skipped checks and legacy-conversion limitations remain distinct.
Reviewed events and known-issue watchlist
The current native schema 2 capture has reviewed rules for every event group, including Intel wireless failures, dump-creation failure, hypervisor mitigation warnings and performance-counter failures. DCOM activation warnings, WMI registration notices and Code Integrity policy metadata receive contextual interpretations rather than automatic fault findings. Rules without external links interpret only the captured message; they do not claim a verified cause. Reliability history contributes reviewed actionable events absent from the bounded logs, deduplicated by provider, ID, normalized message and timestamp to the second. It does not inflate Windows log level totals, and successful update history is omitted from display. Code 22 now applies to any disabled device, including network adapters. Explicit unhealthy disk states and IsSigned=false also receive review findings; missing fields do not establish either problem.
The maintained known-issue list explains matching and sources.
Its machine-readable rules live in config/diagnostics-watchlist.yaml. Warnings link to
the PDF watchlist and vendor advice; the PDF also links Microsoft's driver list.
The watchlist is curated and offline, not an exhaustive or automatically updated
vulnerability database. Compilation makes no network requests for advisories.
Watchlist warnings add zero heuristic penalty: they identify candidates or compatibility risks, while observed event failures retain their existing penalties. No driver date or general vendor reputation triggers a warning. Matching requires exact names/basenames, specified software versions, enabled feature states, and any declared co-installation or event prerequisites. Unknown versions never match an exact-version rule. A filename match cannot prove a binary hash, exploitation, concurrent execution, or that the component caused a crash.
Display limits
Contextual events use a compact interpretation/count table. Actionable event groups show one representative message (600 characters maximum); finding cards show at most 400 evidence characters. Counts, latest times and complete original records remain in the normalized model/source JSON. Routine driver/service lists and successful native command dumps use counts and coverage entries. Selected inventory fields use three records/1,200 characters, with the limits printed in the PDF. Failed command output remains available as bounded evidence. The native 12:10:57 report decreased from 25 pages to 11 in migration validation.