Implementation Plan: Semantic Debt and Incidents

Implement semantic failure management with debt ledger, incident grouping, and semantic change proposals, including governance workflows and evidence capture.

Provenance & Traceability

Architectural Decisions (ADRs)

ADR ID Decision Title Impact on This Plan
ADR-022 Semantic Failure Management Defines debt classification and incident handling.

Product Requirements (PRDs)

PRD ID Requirement Title Satisfied By (SDS) Acceptance Criteria
PRD-006 Semantic Change Proposals SDS-031 §5 Proposal workflow with forced options

Software Design Specifications (SDS)

SDS ID Service/Component Bounded Context SEA-DSL Spec File Implementation Status
SDS-016 Semantic Debt Ledger Service (incl. §7-14 Incidents) shared N/A Designed
SDS-031 Authority & Ownership Boundaries (incl. §5 Decision Execution) shared N/A Draft

Note: SDS-032 (Semantic Change Workflow) has been superseded by SDS-031 §5 (Decision Execution). SDS-033 (Semantic Incidents) has been superseded by SDS-016 §7-14.

Architecture and Design

Design Principles Applied

Dependency Justification

Expected Filetree

1
2
3

/
├── docs/specs/shared/sds/016-semantic-debt-ledger-service.md   # Includes §7-14 for incidents
└── docs/specs/shared/sds/031-authority-ownership-boundaries.md # Includes §5 for decision execution

Proposed Cycles

Cycle Branch Wave Files Modified Files Created Specs Implemented
C1A cycle/p022-c1a-debt-ledger 1 docs/specs/shared/sds/016-semantic-debt-ledger-service.md schemas/events/governance/semantic-debt/* Debt events + dedupe
C1B cycle/p022-c1b-incident-model 1 docs/specs/shared/sds/016-semantic-debt-ledger-service.md (§7-14) — Incident schema
C2A cycle/p022-c2a-change-proposals 2 docs/specs/shared/sds/031-authority-ownership-boundaries.md (§5) — Decision execution workflow

Task Breakdown

Wave 1 (Parallel)

Wave 2 (Depends on Wave 1)

Validation & Verification

Spec Validation

Implementation Validation

Open Questions

  1. Where should debt/incident dashboards live (Workbench vs separate governance UI)? Workbench /governance
  2. What is the minimum set of incident triggers for MVP? Policy violation, evidence failure, drift

Risks & Mitigation

Risk Likelihood Impact Mitigation Strategy
Debt spam overwhelms dashboards Medium Medium Use dedupe keys + incident grouping thresholds.
Approval bottlenecks Medium Medium Use SLA-based escalations and clear role assignments.

Rollback Strategy

  1. Disable automatic incident creation while keeping debt tracking active.

Linked Specifications

Type ID/Doc Document
ADR ADR-022 docs/specs/shared/adr/022-semantic-failure-management.md
PRD PRD-006 docs/specs/shared/prd/006-semantic-change-proposals.md
SDS SDS-016 docs/specs/shared/sds/016-semantic-debt-ledger-service.md (§7-14 = Incidents)
SDS SDS-031 docs/specs/shared/sds/031-authority-ownership-boundaries.md (§5 = Decision Execution)

Supersession Notes: