add-debt

name	add-debt
description	Log a technical-debt item to .planning/DEBT_LOG.md as a markdown table row. v0 stub — preserves /deep-research Phase 5 routing signal while a full debt system remains deferred.
compatibility	agentskills-v1
metadata	{"short-description":"Log a debt item to .planning/DEBT_LOG.md","version":"0.1-stub"}

Document Version: 0.1 (stub) Last Updated: 2026-04-17 Status: ACTIVE (stub)

add-debt (v0 stub)

Append a single debt item to .planning/DEBT_LOG.md as a markdown table row. This is the minimal stub version. A real debt-tracking system (TDMS-style schema, severity scoring pipeline, propagation) is deferred until after the sync-mechanism project.

When to use

• /deep-research Phase 5 reports hasDebtCandidates=true and needs a place to file the candidates
• You want to file a tech-debt item without opening a full debt system
• You hit a limitation, shortcut, or shortcut-shaped decision during work and want to capture it before it slips

When NOT to use

• Cross-session task tracking — use /todo instead
• Bug reports / feature requests — file a GitHub issue
• Plan deferrals with triggers — live in the plan's Post-Foundation Deferrals section until /todo migration (MI-6)

Steps

1. Gather fields by prompting the user (or inferring from conversation context and asking "look right?"):
   • Title — short, actionable
   • Severity — S0 (blocking) / S1 (high) / S2 (normal) / S3 (nit)
   • Category — e.g., security, perf, ux, docs, ports, hygiene
   • Notes — what, why it's debt, and what "paid off" would look like
2. Ensure file exists. If .planning/DEBT_LOG.md is missing, create it with this header:

   # Debt Log
   
   <!-- Generated by /add-debt stub (v0.1). Upgrade trigger: see SKILL.md. -->
   
   | ID  | Title | Severity | Category | Notes | Filed      |
   | --- | ---   | ---      | ---      | ---   | ---        |
   

3. Append the row. Compute next D{N} id as max-existing + 1 (or D1 if empty). Use today's date for Filed. Escape | in user input as \| so the row stays valid markdown.
4. Echo back the filed row to the user for confirmation.

Upgrade trigger

Replace this stub with a full debt system when ANY of these lands:

• A dedicated debt-intake CLI (mirroring scripts/planning/todos-cli.js pattern — locked mutations, regression guard, JSONL source of truth)
• Severity-score propagation (S0/S1 debt surfaces in CLAUDE.md session start or pre-push)
• Cross-link to /todo entries (debt item → todo for the remediation)
• A real volume of items (≥ ~20 rows) making the markdown table unwieldy

When any of these arrive, port or redesign from the SoNash debt system (TDMS-style) following the standard PORT_ANALYSIS.md process.

Guard rails

• Never silently overwrite. This skill appends only. Deleting or editing existing rows requires manual edit of .planning/DEBT_LOG.md.
• No secrets in notes. Treat the file as committed public content.
• No orphan IDs. Deleted IDs are not reused.

Storage

• File: .planning/DEBT_LOG.md (markdown table, source of truth for v0)

Version History

Version	Date	Description
0.1	2026-04-17	Initial stub per D10.