| 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
- 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
- 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 |
| --- | --- | --- | --- | --- | --- |
- 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.
- 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. |
