Tech Debt Tracker
Systematic tracking and management of technical debt. Debt is not inherently bad — it's a trade-off. The problem is untracked debt that compounds silently.
Quick Start
Log a New Debt Item
When debt is identified (during reviews, development, or ad-hoc):
- Categorize: What type of debt is it?
- Severity: How much pain does it cause?
- Effort: How much work to fix?
- Priority: Severity vs effort — is it worth fixing now?
- Log: Add to the registry in
MEMORY.md
Debt Categories
| Category |
Description |
Examples |
| Architecture |
Structural issues that affect the whole system |
Missing module boundaries, circular dependencies, wrong abstraction level |
| Code |
Local code quality issues |
Code smells, duplicated logic, overly complex functions, dead code |
| Test |
Missing or inadequate test coverage |
No tests for critical paths, brittle tests, missing edge case coverage |
| Documentation |
Missing or outdated documentation |
Undocumented public APIs, stale README, missing architecture docs |
| Dependency |
Outdated or problematic dependencies |
Deprecated libraries, unpatched CVEs, abandoned packages, version conflicts |
Severity Levels
| Severity |
Meaning |
Impact |
| Critical |
Blocks progress or causes recurring incidents |
Developers work around it daily, causes bugs |
| High |
Causes ongoing friction and slows development |
Every feature touching this area takes longer |
| Medium |
Noticeable but manageable |
Annoyance, not a blocker. Occasional confusion. |
| Low |
Cosmetic or minor |
Cleanup opportunity, no functional impact |
Effort Estimates
| Effort |
Time |
Scope |
| S |
< 1 hour |
Single function or file change |
| M |
1-4 hours |
Multiple files, focused refactoring |
| L |
4-16 hours |
Cross-module changes, possible API updates |
| XL |
> 16 hours |
Major restructuring, migration, or rewrite |
Priority Matrix
Use severity + effort to determine action:
|
Effort S |
Effort M |
Effort L |
Effort XL |
| Critical |
Fix immediately |
Fix this sprint |
Plan and schedule |
Plan, break into phases |
| High |
Fix now (quick win) |
Fix this sprint |
Schedule within 2 weeks |
Plan, break into phases |
| Medium |
Fix when nearby |
Schedule within 2 weeks |
Backlog |
Backlog (consider living with it) |
| Low |
Fix if touching the file |
Backlog |
Backlog |
Accept the debt |
Quick wins (High severity + S effort, or Critical + S/M effort) should be fixed as soon as possible — they deliver the most value per hour of investment.
Debt Entry Format
When adding to the registry in MEMORY.md:
| Field |
Description |
| ID |
Incremental number (DEBT-001, DEBT-002, ...) |
| Project |
Which project/codebase |
| Category |
Architecture / Code / Test / Documentation / Dependency |
| Description |
What the debt is and why it matters |
| Severity |
Critical / High / Medium / Low |
| Effort |
S / M / L / XL |
| Status |
Open / In Progress / Resolved / Accepted |
| Discovered |
Date the debt was identified |
| Resolved |
Date it was fixed (if applicable) |
Example entry:
| ID |
Project |
Category |
Description |
Severity |
Effort |
Status |
Discovered |
| DEBT-001 |
tui-setup |
Code |
app.rs has cyclomatic complexity 32 in handle_event — needs decomposition |
High |
M |
Open |
2026-02-14 |
| DEBT-002 |
tui-setup |
Test |
No unit tests for parser module — refactoring is risky |
High |
L |
Open |
2026-02-14 |
Debt Review Cadence
When to Review Debt
- During code reviews: Note new debt found during review
- Start of major feature work: Check if the area has known debt that should be addressed first
- Monthly review: Scan the registry for items that have changed priority (became more/less urgent)
- After incidents: Did the debt contribute? Escalate priority if so
Monthly Debt Review Checklist
- Scan the debt registry for stale items (resolved but not marked, or no longer relevant)
- Re-assess priority of open items (has context changed?)
- Identify quick wins that have accumulated
- Propose a "debt sprint" if high-severity items are piling up
- Archive resolved items (move to a "Resolved" section in MEMORY.md)
Debt Reporting
Debt Summary Report
When asked for a debt status report:
## Tech Debt Summary: [Project]
**Date:** YYYY-MM-DD
**Total items:** N (C critical, H high, M medium, L low)
### Quick Wins Available
[S-effort items with High+ severity — easy fixes with big impact]
| ID | Description | Effort |
|---|---|---|
| DEBT-003 | ... | S |
### Top Priority Items
[Highest severity items regardless of effort]
| ID | Description | Severity | Effort |
|---|---|---|---|
| DEBT-001 | ... | Critical | M |
### Trend
[Is debt growing, shrinking, or stable? Any concerning patterns?]
### Recommendations
1. [Prioritized actions]
Integration
- Data: Debt registry maintained in
MEMORY.md (Tech Debt Registry section)
- Cross-reference: architecture-review (discovers structural debt), code-quality (discovers code debt), refactoring-advisor (plans debt remediation)
- Security debt: If debt has security implications (unpatched dependencies, missing input validation), flag to Zero
Arc skill — Technical debt tracking and management
1---2name: tech-debt-tracker3description: Agents should invoke this skill when identifying, categorizing, prioritizing, or planning technical debt work, debt sprints, cleanup backlogs, TODO consolidation, or long-term maintainability risks. Tracks debt with severity/effort.4---56# Tech Debt Tracker78Systematic tracking and management of technical debt. Debt is not inherently bad — it's a trade-off. The problem is *untracked* debt that compounds silently.910## Quick Start1112### Log a New Debt Item1314When debt is identified (during reviews, development, or ad-hoc):15161. **Categorize:** What type of debt is it?172. **Severity:** How much pain does it cause?183. **Effort:** How much work to fix?194. **Priority:** Severity vs effort — is it worth fixing now?205. **Log:** Add to the registry in `MEMORY.md`2122---2324## Debt Categories2526| Category | Description | Examples |27|---|---|---|28| **Architecture** | Structural issues that affect the whole system | Missing module boundaries, circular dependencies, wrong abstraction level |29| **Code** | Local code quality issues | Code smells, duplicated logic, overly complex functions, dead code |30| **Test** | Missing or inadequate test coverage | No tests for critical paths, brittle tests, missing edge case coverage |31| **Documentation** | Missing or outdated documentation | Undocumented public APIs, stale README, missing architecture docs |32| **Dependency** | Outdated or problematic dependencies | Deprecated libraries, unpatched CVEs, abandoned packages, version conflicts |3334---3536## Severity Levels3738| Severity | Meaning | Impact |39|---|---|---|40| **Critical** | Blocks progress or causes recurring incidents | Developers work around it daily, causes bugs |41| **High** | Causes ongoing friction and slows development | Every feature touching this area takes longer |42| **Medium** | Noticeable but manageable | Annoyance, not a blocker. Occasional confusion. |43| **Low** | Cosmetic or minor | Cleanup opportunity, no functional impact |4445---4647## Effort Estimates4849| Effort | Time | Scope |50|---|---|---|51| **S** | < 1 hour | Single function or file change |52| **M** | 1-4 hours | Multiple files, focused refactoring |53| **L** | 4-16 hours | Cross-module changes, possible API updates |54| **XL** | > 16 hours | Major restructuring, migration, or rewrite |5556---5758## Priority Matrix5960Use severity + effort to determine action:6162| | Effort S | Effort M | Effort L | Effort XL |63|---|---|---|---|---|64| **Critical** | Fix immediately | Fix this sprint | Plan and schedule | Plan, break into phases |65| **High** | Fix now (quick win) | Fix this sprint | Schedule within 2 weeks | Plan, break into phases |66| **Medium** | Fix when nearby | Schedule within 2 weeks | Backlog | Backlog (consider living with it) |67| **Low** | Fix if touching the file | Backlog | Backlog | Accept the debt |6869**Quick wins** (High severity + S effort, or Critical + S/M effort) should be fixed as soon as possible — they deliver the most value per hour of investment.7071---7273## Debt Entry Format7475When adding to the registry in `MEMORY.md`:7677| Field | Description |78|---|---|79| ID | Incremental number (DEBT-001, DEBT-002, ...) |80| Project | Which project/codebase |81| Category | Architecture / Code / Test / Documentation / Dependency |82| Description | What the debt is and why it matters |83| Severity | Critical / High / Medium / Low |84| Effort | S / M / L / XL |85| Status | Open / In Progress / Resolved / Accepted |86| Discovered | Date the debt was identified |87| Resolved | Date it was fixed (if applicable) |8889**Example entry:**9091| ID | Project | Category | Description | Severity | Effort | Status | Discovered |92|---|---|---|---|---|---|---|---|93| DEBT-001 | tui-setup | Code | `app.rs` has cyclomatic complexity 32 in `handle_event` — needs decomposition | High | M | Open | 2026-02-14 |94| DEBT-002 | tui-setup | Test | No unit tests for parser module — refactoring is risky | High | L | Open | 2026-02-14 |9596---9798## Debt Review Cadence99100### When to Review Debt101102- **During code reviews:** Note new debt found during review103- **Start of major feature work:** Check if the area has known debt that should be addressed first104- **Monthly review:** Scan the registry for items that have changed priority (became more/less urgent)105- **After incidents:** Did the debt contribute? Escalate priority if so106107### Monthly Debt Review Checklist1081091. Scan the debt registry for stale items (resolved but not marked, or no longer relevant)1102. Re-assess priority of open items (has context changed?)1113. Identify quick wins that have accumulated1124. Propose a "debt sprint" if high-severity items are piling up1135. Archive resolved items (move to a "Resolved" section in MEMORY.md)114115---116117## Debt Reporting118119### Debt Summary Report120121When asked for a debt status report:122123```markdown124## Tech Debt Summary: [Project]125126**Date:** YYYY-MM-DD127**Total items:** N (C critical, H high, M medium, L low)128129### Quick Wins Available130[S-effort items with High+ severity — easy fixes with big impact]131132| ID | Description | Effort |133|---|---|---|134| DEBT-003 | ... | S |135136### Top Priority Items137[Highest severity items regardless of effort]138139| ID | Description | Severity | Effort |140|---|---|---|---|141| DEBT-001 | ... | Critical | M |142143### Trend144[Is debt growing, shrinking, or stable? Any concerning patterns?]145146### Recommendations1471. [Prioritized actions]148```149150---151152## Integration153154- **Data:** Debt registry maintained in `MEMORY.md` (Tech Debt Registry section)155- **Cross-reference:** architecture-review (discovers structural debt), code-quality (discovers code debt), refactoring-advisor (plans debt remediation)156- **Security debt:** If debt has security implications (unpatched dependencies, missing input validation), flag to Zero157158---159160_Arc skill — Technical debt tracking and management_
Firstp1ck