# Diagnostics Report Analyzer Skill

> Analyze AvdLee Diagnostics HTML reports for customer support and debugging. Use this skill whenever the user asks to inspect, summarize, triage, debug, or explain a Diagnostics-Report.html attachment, Diagnostics session logs, embedded diagnostics JSON, legacy HTML-only reports, MetricKit crash diagnostics, app/system metadata, or support reports generated by the Diagnostics framework.

- Skill: `avdlee/diagnostics-report-analyzer-skill` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add avdlee/diagnostics-report-analyzer-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/avdlee/diagnostics-report-analyzer-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: avdlee (https://skillmd.com/u/avdlee)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/avdlee/diagnostics-report-analyzer-skill

---


# Diagnostics Report Analyzer Skill

Use this skill to analyze single-file reports generated by the AvdLee Diagnostics framework. These reports are usually emailed as `.html` attachments and may contain either structured JSON plus a browser renderer or older pre-rendered HTML only.

## Core Principle

Treat the report as diagnostic evidence, not as a webpage to summarize. Newer reports are intentionally designed for agents: they contain a structured JSON payload that is more precise and token-efficient than the rendered HTML.

## Analysis Workflow

### 1. Prefer Embedded JSON

If the report contains this element, extract and parse its text content:

```html
<script id="diagnostics-report-data" type="application/json">
```

Use that JSON as the source of truth. Ignore CSS, JavaScript, navigation markup, and rendered HTML unless a chapter explicitly uses `legacyHTML`.

Expected top-level fields:

- `schemaVersion`: report schema version.
- `title`: human-readable report title.
- `agentHints`: producer-provided analysis hints.
- `chapters`: report sections.

Expected chapter shapes:

- `showTitle`: browser rendering hint; does not affect analysis.
- `kind: "logs"` with `data.sessions`.
- `kind: "table"` with `data.rows`.
- `kind: "text"` or `kind: "preformatted"` with `data.value`.
- `kind: "legacyHTML"` for custom diagnostics or fallback content.
- `legacyHTML`: optional display HTML for chapters that need custom browser rendering. Prefer `data` for analysis unless `data.type` is `legacyHTML` or the structured fields do not answer the question.

### 2. Fall Back To Legacy HTML

If the JSON script tag is absent, parse the HTML report directly:

- Session logs are usually inside `#log-sessions`.
- Sessions are usually wrapped in `.collapsible-session details`.
- Session metadata is often in `<summary><div class="session-header">...`.
- Log levels are usually expressed as `.debug`, `.error`, `.system`, and `.crash`.
- Older reports may only expose crashes as `system` lines such as `SYSTEM: *** Terminating app due to uncaught exception...` or `SYSTEM: *** First throw call stack:`.
- Older plain sessions may use delimiter-like content and `<pre>` blocks.

Keep fallback parsing focused. Do not load or restate the entire HTML file when a small section answers the question.

### 3. Prioritize Evidence

Analyze in this order:

1. Read `agentHints` if present.
2. Inspect app/system metadata for app version, build, OS, device, locale, and environment.
3. Inspect newest sessions first.
4. Prioritize `crash` events, then `error` events, MetricKit diagnostics, and unusual system logs.
5. If a session has no `crash` event, treat crash-like `system` lines as legacy crash evidence, but prefer structured `crash` events when both exist.
6. Compare failing sessions with older sessions only when it helps explain a regression or repeated pattern.
7. Inspect custom chapters for domain-specific state: feature flags, user defaults, directory trees, configuration, account state, or cached files.

## Output Format

Unless the user asks for a different format, respond with:

```markdown
## Summary
One or two sentences describing what most likely happened.

## Evidence
- Specific session, timestamp, event level, metadata row, or chapter detail that supports the conclusion.
- Another relevant detail if needed.

## Recommended Next Steps
- Concrete debugging or support action.
- Code/config area to inspect if apparent.
```

Lead with the most likely explanation. If the evidence is inconclusive, say so and list the missing signal that would disambiguate it.

## Token Discipline

Diagnostics reports can be large. Stay selective:

- Prefer the embedded JSON payload over raw HTML.
- Start with newest sessions and crash/error events.
- Summarize noisy system/debug logs by pattern before quoting individual entries.
- Quote only short snippets that directly support a conclusion.
- Avoid dumping raw logs unless the user explicitly asks.

## Compatibility Notes

Newer Diagnostics reports may include structured sessions and legacy sessions in the same payload because users can update an app after historic logs have already been persisted on device. Treat both as valid evidence.

Legacy HTML chapters may contain trusted report markup created by the Diagnostics framework. Use them when structured data is unavailable, but keep the JSON payload as the preferred machine-readable interface whenever present.