borghei/Claude-Skills / engineering/tech-debt-tracker
tech-debt-tracker
VerifiedScan 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 |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 108k | Updated | Claude CodeCodex | Verified | Install |
| 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: 108k | Updated | Claude CodeCodex | Verified | Install |