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:

<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:

## 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.