12 KiB
Diagnostics reports
diagnostics.typ generates a synthetic Windows health assessment from the text
dump produced by windiagnostics/WindowsMaintenanceReport.ps1.
Quick start
Collect a Full report on Windows, copy the resulting .txt file into
diagnostics/, then run from this repository:
./render-diagnostics.sh diagnostics/windows_system_report_PC.txt "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.txt "Your Name" eridani
Render every .txt 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 dump's Generated:
header and is also mandatory. Missing values stop compilation with an explicit
message.
Pipeline
diagnostics-normalize.typparses the PowerShell text transcript, deduplicates event records, classifies signals, and builds normalized data entirely inside Typst.diagnostics.typvalidates the inputs and selected YAML theme.diagnostics-model.typrenders the final PDF and uses PrimaViz for the summary visualization.
No Python, JSON conversion, or external normalization step is used. Typst reads
the .txt dump directly. It downloads @preview/primaviz:0.10.0 on the first
build and caches it locally.
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 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
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 text dump 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
dump's Generated: header. 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 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 original text dump is passed directly to Typst:
typst compile \
--input diagnostics=diagnostics/windows_system_report_PC.txt \
--input author="Your Name" \
--input theme=cic \
diagnostics.typ \
build/diagnostics/report.pdf
Available themes are default, cic, and eridani and are defined in
themes.yaml.
Input expectations
The parser is designed for Compact, Mid, and Full WinDiagnostics transcripts, but Full provides the evidence needed for meaningful fault synthesis. Unknown future sections still appear in the coverage table and are marked as reviewed and summarized.