design-debt

Design Debt

Harvest design debt and track it in a structured ledger. Read ../knowledge/ops-methods.md ## Design debt and ## Drift detection in full before acting.

Step 1: Locate canonical source

Look for the project design system file in this order:

1. DESIGN.md at repo root
2. system.md or docs/DESIGN.md or docs/system.md
3. Any file matching *DESIGN*.md or *design-system*.md

If no canonical source is found: output NO CANONICAL SOURCE — run design-systems:design-system to generate one, and stop. Do not proceed without a reference to diff against.

Step 2: Drift detection

For each target file (component source, CSS, or directory):

1. Extract token usages: raw values (hex colors, px values, font sizes) and var(--token) references.
2. Run diff between extracted values and the canonical source per ops-methods.md ## Drift detection.
3. Classify each divergence by drift category (token substitution / missing state / breakpoint gap / deprecated pattern / out-of-system value).

Do not infer drift from model judgment when diff can answer deterministically.

Step 3: Harvest debt entries

For each drift finding, create a debt entry per ops-methods.md ## Design debt format:

ID: DEBT-<NNN>
What: <one-sentence description>
Where: <file:line or component name>
Severity: Critical | High | Medium | Low
Fix: <concrete action>
Discovered: <ISO date>
Status: Open

Severity assignment follows ops-methods.md ### Severity guide.

Step 4: Update ledger

Target file: docs/DESIGN-DEBT.md at repo root.

• If the file does not exist: create it with this header, then append entries:

  # Design Debt Ledger
  <!-- Managed by design-ops:design-debt — do not edit IDs manually -->
  

• If the file exists: read it, determine the next DEBT-NNN sequence, append new entries. Never overwrite or reorder existing entries.
• Assign IDs sequentially from the highest existing ID + 1.

Step 5: Summary report

Output: