By name: recording-a-hazard description: Logs, transitions, and signs off a clinical hazard against kit's DCB0129 hazard-log primitive. Use when recording a clinical risk, advancing a hazard's lifecycle, or accepting residual risk. Surfaces the immutable safety-event trail and how the register maps onto the document templates.
Recording a hazard
Spec at compliance/ (the DCB0129 document templates) and
architecture/db.md. The lifecycle API lives in
packages/db/src/schema/clinical/hazard-service.ts.
Why this skill is separate: DCB0129 clinical risk management is a regulated duty -- every hazard change must leave immutable evidence. kit ships the data model + lifecycle API and writes a safety-event audit row on every mutation; the consumer (and their Clinical Safety Officer) owns the actual hazards and the residual-risk acceptance. The Hazard Log register template is a projection of these rows.
Lifecycle
- [ ] Step 1: createHazard -- log it (status `open`), records `hazard.opened`
- [ ] Step 2: transitionHazardStatus -- advance open -> mitigating -> controlled -> closed, records `hazard.transitioned`
- [ ] Step 3: signOffHazard -- record residual-risk acceptance + the accountable actor, records `hazard.signed-off`
- [ ] Step 4: read the register with openHazards / hazardsBySeverity
How evidence works
Each call records one append-only audit_log row under the safety-event taxonomy (SAFETY_EVENT_ACTIONS:
hazard.opened / hazard.transitioned / hazard.signed-off), purpose: clinical-safety,
legalBasis: legal-obligation, inside the same transaction as the write. Immutability comes from the existing
append-only audit_log trigger, not a new table -- the hazard row's columns carry only its current state; the trail
is the history. A transition to the status it already holds is a no-op and records nothing.
Notes
signOffHazardstampssignedOffBy/signedOffAtand the residual rating; an optional terminal status sets the lifecycle state in the same call. The accountable actor is the CSO or their delegate.createHazardcarries severity x likelihood -> initial risk rating; the acceptability matrix that maps a rating to accept / control / reject is policy the consumer defines in their Clinical Risk Management Plan.
Non-goals
- The clinical judgement -- which hazards exist, their severity, and whether residual risk is acceptable. kit records the decision; the CSO makes it.
- HTTP exposure: the primitive is the typed db API; a route is the consumer's call (route it through
keeping-sdk-in-syncif added).