Skip to content
Analytics Engineering
Start free

Data Quality Incident Write-Up Template

Copy a blameless data-quality incident template covering impact, detection, timeline, evidence, root cause, resolution, validation, prevention, ownership, and communication.

Use this when

Use this after a data-quality event affected—or could have affected—a report, model, metric, pipeline, or decision.

How to use it
  1. 01Write observed evidence separately from hypotheses and later conclusions.
  2. 02Describe the consumer impact in business terms, not only the failed job.
  3. 03Assign prevention work to owners with dates and a verification method.
Template

Copy it. Replace the brackets. Delete what does not apply.

# Data quality incident: [short descriptive title]

## Status

- **State:** [investigating / mitigated / resolved / monitoring]
- **Severity:** [team definition]
- **Incident owner:** [name or team]
- **Started:** [YYYY-MM-DD HH:MM timezone]
- **Detected:** [YYYY-MM-DD HH:MM timezone]
- **Resolved:** [YYYY-MM-DD HH:MM timezone or open]
- **Last updated:** [YYYY-MM-DD HH:MM timezone]

## Executive summary

[In 3–5 sentences: what data was wrong or unavailable, who was affected, the decision/reporting risk, current status, and the most important next action.]

## Consumer impact

- **Affected consumers:** [teams, dashboards, reports, models, APIs]
- **Affected period:** [coverage]
- **Decision risk:** [what someone could have concluded or done]
- **Data exposure:** [incorrect / incomplete / delayed / duplicated / unavailable]
- **Confirmed usage:** [known views, exports, decisions, or “not yet confirmed”]

## Scope

### Affected

- [model.metric.column]

### Not affected

- [adjacent system checked and evidence]

### Unknown

- [genuine uncertainty and next check]

## Detection

- **Signal:** [test, monitor, stakeholder report, reconciliation]
- **Expected behavior:** [contract or threshold]
- **Observed behavior:** [bounded evidence]
- **Why earlier controls did or did not catch it:** [specific gap]

## Timeline

| Time | Event | Evidence / decision |
|---|---|---|
| [time] | [source change, deployment, alert, report] | [link/query/log] |

## Immediate response

1. [Stopped, isolated, labeled, or rolled back the affected output.]
2. [Notified known consumers with scope and uncertainty.]
3. [Preserved evidence and identified the last known-good state.]

## Investigation

### Hypothesis 1: [statement]

- **Why plausible:** [evidence]
- **Smallest test:** [query/check]
- **Result:** [supported / rejected / unresolved]

### Hypothesis 2: [statement]

- **Why plausible:** [evidence]
- **Smallest test:** [query/check]
- **Result:** [supported / rejected / unresolved]

## Root cause

[Describe the technical and process conditions that produced the incident. Avoid naming a person as the cause.]

### Contributing factors

- [missing contract, ambiguous ownership, test gap, late source behavior, deployment condition]

## Resolution

- **Change made:** [code/config/data correction]
- **Records affected:** [bounded count and period]
- **Backfill or restatement:** [scope and method]
- **Consumer communication:** [what was sent, to whom, and when]

## Validation

- [ ] Reproduced the failure before the fix where safe.
- [ ] Confirmed the targeted test passes after the fix.
- [ ] Reconciled corrected totals to an independent source.
- [ ] Checked adjacent dates, entities, and downstream models.
- [ ] Confirmed dashboards/extracts refreshed from corrected data.
- [ ] Monitored for recurrence during [period].

## Prevention actions

| Action | Owner | Due date | Verification | Status |
|---|---|---|---|---|
| [specific control or contract] | [team] | [date] | [test/alert/review] | [open] |

## Communication record

- **Initial notice:** [time, audience, message link]
- **Scope update:** [time, audience, message link]
- **Resolution notice:** [time, audience, message link]

## Lessons

- **What worked:** [detection, response, collaboration]
- **What failed safely:** [control that limited impact]
- **What needs to change:** [system or process]
- **What remains uncertain:** [follow-up evidence]

## Appendix

- [queries]
- [logs]
- [screenshots with sensitive data removed]
- [related pull requests]
- [source contract or metric definition]
Learn before you fill it in

Related guidance.