The Knowledge Debt Ledger

Knowledge debt is the accumulated stock of content that is stale, incomplete, contradictory, or missing. It builds slowly and is invisible until a user makes a decision based on wrong information — at which point the debt has converted to a real cost. The knowledge debt ledger is a living document that tracks known debt items, their estimated impact, their assigned owner, and their remediation timeline.

The ledger does not fix debt — it makes debt visible and forces prioritization. Untracked debt gets ignored. Tracked debt gets worked.

1. Stale Content Content where the last-reviewed date exceeds the staleness threshold for that content type. Thresholds vary by type: runbooks should be reviewed quarterly (90 days), articles every 6 months (180 days), decision records annually (365 days). Stale content is automatically flagged in the debt ledger by a scheduled query. Flag does not mean deletion — it means the debt is tracked and an owner is accountable for review.
2. Incomplete Content Content that is missing required schema fields, has an empty summary, lacks a trigger condition (runbooks), or has a placeholder body ("TODO: write this section"). Incomplete content was published to avoid blocking a workflow — the author intended to come back. Most of them do not. The debt ledger flags incomplete items at publication and again after 30 days with no update.
3. Contradictory Content Two or more items that give conflicting instructions for the same process or conflicting answers to the same question. This is the most dangerous debt type: a user reads one authoritative-looking source, follows the instructions, and gets a wrong outcome. Contradiction detection is partially automated (semantic similarity across content items with the same topic tags) and partially manual (users who encounter contradictions should have a one-click "flag conflict" mechanism).
4. Known Gaps Processes or concepts that are known to be undocumented. Known gaps accumulate from three sources: Slack questions that the bot could not answer, ticket resolutions where the engineer noted "no runbook for this," and onboarding experiences where new hires identify missing reference content. Log known gaps in the debt ledger with the source context — a gap that surfaces in three different channels is a higher-priority gap than one that surfaces once.

interface KnowledgeDebtItem {
  id: string;
  type: 'stale' | 'incomplete' | 'contradictory' | 'known-gap';
  severity: 'critical' | 'high' | 'medium' | 'low';
  affectedContentIds: string[];       // Empty for known-gap type
  description: string;
  detectedAt: string;                 // ISO date
  detectedBy: 'automated' | string;  // User ID for manual flags
  assignedOwner: string | null;
  dueDate: string | null;
  status: 'open' | 'in-progress' | 'resolved' | 'accepted-risk';
  source?: string;                    // For known-gaps: "Slack #eng 2026-02-14" etc.
}

// Severity heuristics
function calculateSeverity(item: Partial<KnowledgeDebtItem>): KnowledgeDebtItem['severity'] {
  if (item.type === 'contradictory') return 'critical';   // Always critical
  if (item.type === 'known-gap') {
    // Gaps cited in 3+ sources are high severity
    return 'high';
  }
  if (item.type === 'stale') {
    // Stale runbooks are higher severity than stale articles
    // (procedural content degrades faster than explanatory content)
    return 'high';
  }
  // Incomplete content: severity depends on which fields are missing
  // Missing summary: high (breaks AI retrieval)
  // Missing trigger condition on runbook: high
  // Missing related_articles: low
  return 'medium';
}