# Tech Debt Tracker

> Detect and track technical debt from conversation and PR review comments. Resurface in weekly retros, promote to commitments when ready to fix.

- Skill: `suyoumo/tech-debt-tracker` (Agent Skill)
- Install (CLI): `npx skillmds@latest add suyoumo/tech-debt-tracker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/suyoumo/tech-debt-tracker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: suyoumo (https://skillmd.com/u/suyoumo)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/suyoumo/tech-debt-tracker

---


# Tech Debt Tracker

Track technical debt from conversation and PR review comments. Debt items live in `projects/commitments/tech-debt/` and are resurfaced weekly.

## Mode A: Passive detection

When the user says something implying tech debt ("this is a hack but it works", "we should really refactor the auth module", "adding another TODO"), silently extract it.

**Action:**
1. Check for duplicates via `memory_search` in `projects/commitments/tech-debt/`.
2. Write to `projects/commitments/tech-debt/<slug>.md`:

```
---
type: tech-debt
detected_at: <today YYYY-MM-DD>
repo: <current repo context if known, else null>
severity: <high|medium|low>
category: <refactor|performance|security|testing|documentation|architecture>
source: conversation
source_pr: null
---
# <Brief title>
<What the debt is and why it exists.>

## Context
<What prompted the shortcut — deadline, complexity, missing knowledge.>

## Proposed fix
<What a proper fix would look like, if discussed.>
```

**Severity rules:**
- `high`: security shortcuts, data integrity risks, architectural violations
- `medium`: code quality, missing tests, poor abstractions
- `low`: style issues, minor workarounds, documentation gaps

3. At a natural pause: "Tracked tech debt: <brief description>."

Do NOT interrupt conversation flow.

## Mode B: PR review scan (used by triage mission)

When the triage mission processes recently merged PRs, it should scan review comments for tech-debt patterns:
- "can be addressed in follow-up work"
- "not blocking but should fix later"
- "TODO: address in next PR"
- "leaving for now", "good enough for now"
- "nit: ... (not blocking)"
- "tech debt", "hack", "workaround" in review comments

For each match, create a tech-debt item with `source: pr-review` and `source_pr: owner/repo#123`.

## Mode C: Explicit capture

User says: "add tech debt: the caching layer needs TTL eviction."

Write directly to `projects/commitments/tech-debt/`, confirm briefly.

## Mode D: Listing

User says: "show tech debt" or "debt backlog"

**Action:**
1. `memory_tree("projects/commitments/tech-debt/", depth=1)` — list files (skip README.md)
2. `memory_read` each for title, severity, detected_at, repo, source
3. Display grouped by severity, then age:

```
## Tech Debt Backlog

### High Severity
- **<title>** (repo: <repo>, <N> days old, source: <conversation|PR #X>) — <category>

### Medium Severity
- ...

### Low Severity
- ...

---
<count> total. <count> chronic (30+ days).
Say "resolve <title>" to mark fixed, or "promote <title>" to create a commitment.
For large items, use `/plan <description>` to create a structured fix plan.
```

## Mode E: Resolution

User says: "resolved the caching TTL debt"

Move to `projects/commitments/resolved/` with original type preserved. Confirm.

## Mode F: Promotion to commitment

User says: "let's fix the auth refactor" or "promote the caching debt"

Create commitment in `projects/commitments/open/` with `tags: [tech-debt]` and `resolution_path: agent_can_handle` if it's a code task. For complex items, suggest: "This looks like a multi-step refactor. Use `/plan <description>` to create a structured fix plan."

## Filename conventions

Slugify: lowercase, hyphens, max 50 chars. Prefix with repo slug if known:
- "Auth module needs refactor" in nearai/ironclaw → `nearai-ironclaw-auth-refactor.md`
- Generic debt → `caching-ttl-eviction.md`