incident-report

Turn a finished investigation into a polished, browser-viewable HTML report artifact — the kind a stakeholder (often non-engineer, often reading Hebrew/RTL) opens in one click and scans in a minute. Published with the Artifact tool.

This is the render/publish step, downstream of the investigation — it presents a finding that is already established, it does not discover one. Consumes the output of identify-bug (root-cause understanding) and obs-logs (the evidence numbers).

When to use

• An incident / postmortem / production-bug writeup, or an investigation result, needs to go to a human (a lead, leadership, a client-facing summary).
• You already have the facts: root cause, evidence (real numbers), impact, timeline, and — if any — the fix.

Not for: an internal handoff doc for whoever fixes it (that is identify-bug, plain markdown), or capturing a decision (that is decision-record).

How to build one

1. Start from the template — copy report-template.html. It carries the full design system (palette, type, every component's CSS) and a section skeleton with <PLACEHOLDER> markers.
2. Fill placeholders with real data; delete sections that don't apply. Never lorem, never a guessed number. Every count, id, timestamp, and code line is a value you actually verified. A report with invented figures is worse than no report.
3. Keep it concise — lead with the verdict; one screenful conveys the gist; detail and long lists go lower or behind a link. See the concise-human-read-text team rule. A report is a briefing, not a transcript.
4. Publish with the Artifact tool — a stable emoji favicon (🔗 / 🐛 / 📊; keep it the same across redeploys), a concise <title>. Re-deploy to the same file path to update in place.

Sections — include what the report needs

Numbered in the template where order carries meaning; skip any that don't apply.

• Hero + status chips — eyebrow (doc type · env), one-line title of what broke, one-paragraph summary, chips (severity, env, a verified-safe claim, tracker id). Always.
• Executive summary card — the ~4 headline metrics a manager needs (impact count, scope, verified-safe figure, current status). When there are headline numbers.
• Root cause + failure flow — the mechanism, as a numbered .flow ending in a .step.bug marker at the point of failure; an info note on why it looked healthy. Core of an incident report.
• Evidence — hard, verifiable observations (counts, timestamps, id ranges, source components). Proves the cause instead of asserting it.
• Blast radius — the direct hit vs any secondary/adjacent effect. When impact has more than one axis.
• Impact / financial verification — why the feared harm structurally can't happen, then a table comparing the incident window to a baseline, ending in a verdict row. When the reader fears something costlier (money, data loss, duplication).
• Who's affected — technical impact translated into human/customer groups. When real users were touched.
• The fix — paired fix cards (root-cause + defense-in-depth), a dir="ltr" code snippet, a note on PR / required reviews / recovery. When there is a remedy.
• Timeline — horizontal, left→right, dated nodes (crit for onset, good for resolution). When events unfold over time.
• Footer — evidence sources, verification scope, accurate-as-of date. Always.
• Callout notes — reusable good / crit / info blocks dropped inline anywhere; 1–3 per section, don't overuse.

Hard rules (RTL + artifact safety)

The template already encodes these; keep them if you hand-edit:

• Whole doc dir="rtl" lang="he" for Hebrew; use logical (inline) CSS properties so it mirrors.
• Code is always dir="ltr" (blocks and inline <code>) or identifiers scramble on an RTL page.
• In Hebrew prose, arrows point ← (left), not →.
• tabular-nums on every aligned digit (tables, metrics, timeline dates).
• Wide content (tables, code, timeline, id-lists) scrolls inside its own overflow-x:auto; the page body never scrolls sideways.
• System fonts only — the artifact CSP blocks webfonts; no @import / <link> for fonts.
• Self-contained: one inline <style>, no external CSS/JS/images/CDN. Author page content directly (leading <div dir="rtl" lang="he" class="page">), no <html>/<head>/<body> (publish-time adds them).
• The horizontal timeline is dir="ltr" (chronology reads left→right) even on the RTL page; flip only the per-node label back to dir="rtl".

Semantic status color is fixed: crit = red (damage/failure), good = green (verified-safe/resolved), info/accent = blue (neutral explanation), warn = amber (caution). It is separate from any brand accent.

References

• report-template.html — the copy-paste starting point (design system + section skeleton).
• The bundled artifact-design skill — general craft; this skill fixes the format so incident reports stay consistent across authors and sessions.
• docs/methodology/artifact-types.md — type justification (a Skill: a repeatable render procedure with a bundled asset).