@puberty-labs/refuctor/templates/TECHDEBT.md

AI-powered, snark-fueled technical debt cleansing suite with automatic snarky language detection that turns code cleanup into a darkly humorous financial metaphor.

# Technical Debt Tracker

> "Address technical debt the moment it's identified"

## 🎯 Philosophy

**IMMEDIATE TECH DEBT RESOLUTION** - No debt survives more than one session
without explicit prioritization and timeline. Every debt item gets timestamp,
priority, and accountability.

## 🚨 Active Debt (PRIORITY ORDER)

### P1 - Critical (Fix Immediately)

No critical debt items - maintaining clean codebase

### P2 - High (Fix This Session)

No high priority debt items - clean slate achieved

### P3 - Medium (Fix Next Session)

No medium priority debt items - excellent technical hygiene

### P4 - Low (Fix When Convenient)

No low priority debt items - zero debt status achieved

## ✅ Resolved Debt (Session History)

### Session [DATE] - Initial Setup

- [x] **TECHDEBT.md Template**: Deployed technical debt tracking system
- [x] **Refuctor Integration**: Automated debt detection configured
- [x] **Clean Slate**: Starting with zero technical debt

#### TOTAL DEBT ELIMINATED: 0 warnings (starting clean)

#### SESSION IMPACT: 100% technical debt prevention system deployed

## 🛠️ Automated Debt Detection Commands

### Comprehensive Scan (Run During Session Wrap)

```bash

# Markdown linting

npx --yes markdownlint-cli "*.md"

# Spell checking

npx --yes cspell "**/*.{md,js,json,ts}" "*.mdc"

# Security audit (when package.json exists)

npm audit

# Refuctor comprehensive scan

refuctor scan --verbose
```text

### Real-time Monitoring

- **IDE Warning Count**: Monitor status bar indicators
- **Git Status**: `git status --porcelain` for uncommitted changes
- **File Count Growth**: Track project bloat via `find . -type f | wc -l`

## 📊 Debt Categories & Thresholds

### Automatic P1 (Critical) Triggers

- **Security vulnerabilities**: Any high/critical CVE
- **Linting errors**: >50 warnings in any single file
- **Broken builds**: Any compilation failures
- **Dead URLs**: Broken external links in documentation

### P2 (High) Triggers

- **Linting warnings**: 10-50 warnings per file
- **Spell check issues**: >5 unknown words (excluding project terminology)
- **TODO comments**: Any TODO without corresponding GitHub issue
- **Unused dependencies**: Dependencies in package.json but not imported

### P3 (Medium) Triggers

- **Code duplication**: Significant duplicate logic patterns
- **Performance warnings**: Bundle size >1MB, load time >3s
- **Documentation drift**: README older than 2 versions behind
- **Configuration inconsistency**: Conflicting settings across config files

### P4 (Low) Triggers

- **Minor style inconsistencies**: Non-critical formatting issues
- **Optimization opportunities**: Performance improvements with minimal impact
- **Nice-to-have refactoring**: Code cleanup that doesn't affect functionality

## 🔥 Session Wrap Integration

**MANDATORY EXECUTION:** Every session wrap MUST run debt detection and update
this file.

### New Debt Protocol

1. **DETECT**: Run `refuctor scan` and automated scanning commands
2. **CATEGORIZE**: Assign priority based on thresholds above
3. **LOG**: Add to appropriate priority section with timestamp
4. **COMMIT**: Include debt status in session wrap commit message

### Debt Resolution Protocol

1. **FIX**: Address debt items in priority order
2. **VERIFY**: Re-run `refuctor scan` to confirm resolution
3. **MOVE**: Transfer resolved items to "Resolved Debt" section
4. **TIMESTAMP**: Mark resolution session and impact

## 🎨 Debt Personality (Refuctor Style)

### Debt Shame Levels

- **P1 Critical**: *"This is fucking embarrassing. Fix it NOW."*
- **P2 High**: *"We're taking back the repo. Clean this today."*
- **P3 Medium**: *"A bit crusty. Handle it this sprint."*
- **P4 Low**: *"Minor blemish. But you'll pay later…"*

### Financial Metaphors

- **Foreclosure**: P1 critical debt that's blocking development
- **Repossession**: P2 high debt that needs immediate attention
- **Liens Filed**: P3 medium debt that's accumulating interest
- **Interest Accruing**: P4 low debt that's slowly growing

### Clean Slate Achievement

Zero debt, you magnificent developer!

---

## 📋 Current Status: ✅ ZERO TECHNICAL DEBT

**Last Updated**: [DATE]

**Debt-Free Sessions**: Starting fresh

**Total Debt Eliminated This Session**: 0 warnings (clean start)

**Status**: *"Clean slate, ready to build something beautiful."*

## 🚀 Next Session Goals

- Maintain zero debt status
- Implement automated debt prevention
- Configure project-specific spell checking
- Establish regular session wrap protocol

---

## 📋 Footer

Built with Refuctor - The Debt Cleansing Syndicate

Because your code deserves better than being held hostage by technical debt.