tech-debt-tracking

Tech Debt Tracking

Purpose

Every shortcut has a cost. This skill ensures shortcuts are conscious decisions with documented justifications, not accidents that compound silently.

When to Track

• Skipping tests for time pressure
• Using a workaround instead of a proper fix
• Hardcoding a value that should be configurable
• Writing a TODO comment
• Bypassing a quality gate with justification
• Using a deprecated API or pattern
• Choosing a quick solution over the correct one

How to Track

Add an entry to .shipworthy/tech-debt.md:

## [Short Description]
- **Date**: YYYY-MM-DD
- **Severity**: low | medium | high | critical
- **Effort to fix**: hours | days | weeks
- **Justification**: Why was this shortcut taken?
- **Impact if not fixed**: What happens if this stays forever?
- **Files affected**: List specific files

Rules

1. Every shortcut requires justification — "I didn't have time" is a valid justification, but document it
2. No silent TODOs — every TODO in code must have a corresponding entry in tech-debt.md
3. Review at session start — the session-start hook surfaces the debt count
4. Debt has a severity — critical debt should be fixed before adding new features
5. Debt has a shelf life — if it's been there >30 days with no plan to fix, escalate the conversation

When to Pay Down Debt

• Before starting a new feature in the same area
• When the debt is causing real problems (bugs, slowness, confusion)
• During dedicated refactoring time
• When the effort to work around the debt exceeds the effort to fix it

Anti-Patterns

• Tracking debt but never paying it down
• Not tracking debt at all ("we'll remember")
• Treating all debt as equal (prioritize by severity and impact)
• Using debt tracking as an excuse to write sloppy code ("I'll track it as debt")