Skip to content

borghei/Claude-Skills / engineering/tech-debt-tracker

tech-debt-tracker

Verified

Scan codebases for technical debt with AST parsing, prioritize by impact, and generate trend dashboards. Use when tracking tech debt, prioritizing refactoring, calculating cost-of- delay, planning sprint debt, or reporting debt to execs.

references/quadrant-and-roadmap.md

View on GitHub
# Tech Debt Tracker -- Reference Material

## Technical Debt Quadrant (Martin Fowler)

**Quadrant 1: Reckless & Deliberate**
- "We don't have time for design"
- Highest priority for remediation

**Quadrant 2: Prudent & Deliberate**
- "We must ship now and deal with consequences"
- Schedule for near-term resolution

**Quadrant 3: Reckless & Inadvertent**
- "What's layering?"
- Focus on education and process improvement

**Quadrant 4: Prudent & Inadvertent**
- "Now we know how we should have done it"
- Normal part of learning, lowest priority

## Detailed Detection Heuristics

### Code Debt Indicators
- Long functions (>50 lines for complex logic, >20 for simple operations)
- Deep nesting (>4 levels of indentation)
- High cyclomatic complexity (>10)
- Duplicate code patterns (>3 similar blocks)
- Missing or inadequate error handling
- Poor variable/function naming
- Magic numbers and hardcoded values
- Commented-out code blocks

### Architecture Debt Indicators
- Monolithic components that should be modular
- Circular dependencies between modules
- Violation of separation of concerns
- Inconsistent data flow patterns
- Over-engineering or under-engineering for current scale
- Tightly coupled components
- Missing abstraction layers

### Test Debt Indicators
- Low test coverage (<80% for critical paths)
- Missing unit tests for complex logic
- No integration tests for key workflows
- Flaky tests that pass/fail intermittently
- Slow test execution (>10 minutes for unit tests)
- Tests that don't test meaningful behavior
- Missing test data management strategy

### Documentation Debt Indicators
- Missing API documentation
- Outdated README files
- No architectural decision records (ADRs)
- Missing code comments for complex algorithms
- No onboarding documentation
- Inconsistent documentation formats
- Documentation that contradicts implementation

### Dependency Debt Indicators
- Outdated packages with known security vulnerabilities
- Dependencies with incompatible licenses
- Unused dependencies bloating the build
- Version conflicts between packages
- Deprecated APIs still in use
- Heavy dependencies for simple tasks
- Missing dependency pinning

### Infrastructure Debt Indicators
- Manual deployment processes
- Missing monitoring and alerting
- Inadequate logging
- No disaster recovery plan
- Inconsistent environments (dev/staging/prod)
- Missing CI/CD pipelines
- Infrastructure as code gaps

## Implementation Roadmap

### Phase 1: Foundation (Weeks 1-2)
1. Set up debt scanning infrastructure
2. Establish debt taxonomy and scoring criteria
3. Scan initial codebase and create baseline inventory
4. Train team on debt identification and reporting

### Phase 2: Process Integration (Weeks 3-4)
1. Integrate debt tracking into sprint planning
2. Establish debt budgets and allocation rules
3. Create stakeholder reporting templates
4. Set up automated debt scanning in CI/CD

### Phase 3: Optimization (Weeks 5-6)
1. Refine scoring algorithms based on team feedback
2. Implement trend analysis and predictive metrics
3. Create specialized debt reduction initiatives
4. Establish cross-team debt coordination processes

### Phase 4: Maturity (Ongoing)
1. Continuous improvement of detection algorithms
2. Advanced analytics and prediction models
3. Integration with planning and project management tools
4. Organization-wide debt management best practices

## Success Criteria

**Quantitative targets (6 months)**:
- 25% reduction in debt interest rate
- 15% improvement in development velocity
- 30% reduction in production defects
- 20% faster code review cycles

**Qualitative targets**:
- Improved developer satisfaction scores
- Reduced context switching during feature development
- Faster onboarding for new team members
- Better predictability in feature delivery timelines

## Common Pitfalls

| Pitfall | Solution |
|---------|----------|
| Analysis paralysis | Set time limits for analysis; use "good enough" scoring |
| Perfectionism | Focus on high-impact debt; accept some debt is acceptable |
| Ignoring business context | Tie debt work to business outcomes and customer impact |
| Inconsistent adoption | Make debt tracking part of standard development workflow |
| Tool over-engineering | Start simple; iterate based on actual usage patterns |
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall