270 lines
12 KiB
Markdown
270 lines
12 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
./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:
|
||
|
||
```bash
|
||
./render-diagnostics.sh diagnostics/windows_system_report_PC.txt "Your Name" eridani
|
||
```
|
||
|
||
Render every `.txt` dump under `diagnostics/` recursively:
|
||
|
||
```bash
|
||
./render-diagnostics.sh --all "Your Name"
|
||
```
|
||
|
||
Select a non-default theme for the complete batch:
|
||
|
||
```bash
|
||
./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:
|
||
|
||
```text
|
||
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
|
||
|
||
1. `diagnostics-normalize.typ` parses the PowerShell text transcript,
|
||
deduplicates event records, classifies signals, and builds normalized data
|
||
entirely inside Typst.
|
||
2. `diagnostics.typ` validates the inputs and selected YAML theme.
|
||
3. `diagnostics-model.typ` renders 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:
|
||
|
||
1. **Executive overview** — the short first-page health assessment, capacity
|
||
metrics, heuristic health graph, priority findings, and signal chart.
|
||
2. **Findings requiring attention** — a resolution plan for every actionable
|
||
exception, followed by its correlated, deduplicated event evidence.
|
||
3. **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 `OK` and 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:
|
||
|
||
```yaml
|
||
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**:
|
||
|
||
1. Save the original PDF and text dump if the issue may need escalation or an
|
||
audit trail.
|
||
2. Follow the finding's numbered **Resolution path**. Use its linked vendor or
|
||
Microsoft guidance when one is provided.
|
||
3. 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.
|
||
4. Reboot when the repair changes system files, drivers, services, firmware, or
|
||
pending installer state.
|
||
5. Reproduce the original workload where practical, then run WinDiagnostics
|
||
again and compile the new dump.
|
||
6. 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](https://learn.microsoft.com/en-us/troubleshoot/windows-client/setup-upgrade-and-drivers/system-log-event-id-7000-7026)
|
||
- [Microsoft Defender status fields](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/defender/msft-mpcomputerstatus)
|
||
- [Win32_Battery fields](https://learn.microsoft.com/en-us/windows/win32/cimwin32prov/win32-battery)
|
||
- [DISM and SFC repair sequence](https://support.microsoft.com/en-us/windows/experience/backup-recovery/using-system-file-checker-in-windows)
|
||
- [Enable Windows Firewall profiles](https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/configure-with-command-line)
|
||
|
||
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:
|
||
|
||
```bash
|
||
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.
|