749 lines
22 KiB
Markdown
749 lines
22 KiB
Markdown
# /sdd:story-tech-debt
|
||
|
||
## Meta
|
||
- Version: 2.0
|
||
- Category: story-analysis
|
||
- Complexity: high
|
||
- Purpose: Identify, categorize, prioritize, and track technical debt from stories to inform debt reduction efforts
|
||
|
||
## Definition
|
||
**Purpose**: Scan all stories for technical debt indicators, categorize by severity and type, calculate impact metrics, and generate actionable debt reduction plan.
|
||
|
||
**Syntax**: `/sdd:story-tech-debt [priority]`
|
||
|
||
## Parameters
|
||
| Parameter | Type | Required | Default | Description | Validation |
|
||
|-----------|------|----------|---------|-------------|------------|
|
||
| priority | string | No | "all" | Debt priority filter (critical, important, nice-to-have, all) | One of: critical, important, nice-to-have, all |
|
||
|
||
## INSTRUCTION: Analyze Technical Debt
|
||
|
||
### INPUTS
|
||
- priority: Optional priority filter (defaults to all)
|
||
- Story files from all directories:
|
||
- `/docs/stories/development/` - Active stories
|
||
- `/docs/stories/review/` - Stories in review
|
||
- `/docs/stories/qa/` - Stories in testing
|
||
- `/docs/stories/completed/` - Finished stories
|
||
- Optional: Project codebase for TODO scanning
|
||
|
||
### PROCESS
|
||
|
||
#### Phase 1: Debt Indicator Detection
|
||
1. **SCAN** all story files for debt indicators:
|
||
- "TODO" mentions in technical notes
|
||
- "FIXME" mentions in technical notes
|
||
- "HACK" mentions in technical notes
|
||
- "Technical debt" explicit mentions
|
||
- "Deferred" items in implementation checklist
|
||
- "Temporary solution" in progress log
|
||
- "Skipped tests" in test cases
|
||
- "Performance concern" in technical notes
|
||
- "Security risk" mentions
|
||
- "Needs refactor" mentions
|
||
|
||
2. **EXTRACT** debt details:
|
||
- Description of debt item
|
||
- Source story ID
|
||
- Date created (from story started date)
|
||
- Severity indicators
|
||
- Impact description
|
||
|
||
3. **OPTIONAL**: Scan codebase for TODOs:
|
||
- Search `*.php` files for TODO comments
|
||
- Search `*.blade.php` files for TODO comments
|
||
- Search `*.js` files for TODO comments
|
||
- Link to stories when possible
|
||
|
||
#### Phase 2: Debt Categorization
|
||
1. **CLASSIFY** debt by severity:
|
||
- Critical: Security/Stability issues
|
||
- Important: Performance/Maintenance issues
|
||
- Nice to have: Cleanup/Refactor items
|
||
|
||
2. **CLASSIFY** debt by type:
|
||
- Security debt
|
||
- Performance debt
|
||
- Code quality debt
|
||
- Test debt
|
||
- Documentation debt
|
||
- Infrastructure debt
|
||
|
||
3. **CALCULATE** impact scores:
|
||
- User impact (High/Medium/Low)
|
||
- Developer impact (High/Medium/Low)
|
||
- Business impact (High/Medium/Low)
|
||
|
||
4. **ESTIMATE** effort:
|
||
- Hours for small items
|
||
- Days for medium items
|
||
- Weeks for large items
|
||
|
||
5. **DISPLAY** debt inventory:
|
||
```
|
||
🏗️ TECHNICAL DEBT INVENTORY
|
||
══════════════════════════════════
|
||
|
||
🔴 CRITICAL (Security/Stability)
|
||
────────────────────────────────
|
||
[DEBT-001] Security: Unencrypted Sensitive Data Storage
|
||
- Story: STORY-2025-012
|
||
- Created: Sep 15, 2025
|
||
- Impact: High - PII at risk, compliance violation
|
||
- Effort: Medium (2 days)
|
||
- Priority: P0 - Fix immediately
|
||
- Description: User passwords stored in plain text in logs
|
||
|
||
[DEBT-002] Stability: Memory Leak in Background Service
|
||
- Story: STORY-2025-023
|
||
- Created: Sep 20, 2025
|
||
- Impact: High - Application crashes after 24h
|
||
- Effort: Low (1 day)
|
||
- Priority: P0 - Fix immediately
|
||
- Description: Queue worker accumulates memory over time
|
||
|
||
🟡 IMPORTANT (Performance/Maintenance)
|
||
────────────────────────────────────
|
||
[DEBT-003] Performance: Unoptimized Database Queries
|
||
- Story: STORY-2025-018
|
||
- Created: Sep 18, 2025
|
||
- Impact: Medium - 3-5s page load times
|
||
- Effort: Medium (2 days)
|
||
- Priority: P1 - Fix soon
|
||
- Description: N+1 queries in user dashboard
|
||
|
||
[DEBT-004] Maintenance: Duplicated Business Logic
|
||
- Story: STORY-2025-025
|
||
- Created: Sep 22, 2025
|
||
- Impact: Medium - Hard to update, bug prone
|
||
- Effort: High (3 days)
|
||
- Priority: P2 - Plan for next sprint
|
||
- Description: Payment validation duplicated in 5 places
|
||
|
||
🟢 NICE TO HAVE (Cleanup/Refactor)
|
||
──────────────────────────────────
|
||
[DEBT-005] Cleanup: Unused Dependencies
|
||
- Story: STORY-2025-010
|
||
- Created: Sep 10, 2025
|
||
- Impact: Low - Larger bundle size
|
||
- Effort: Low (2 hours)
|
||
- Priority: P3 - When time permits
|
||
- Description: 3 unused npm packages in package.json
|
||
|
||
[DEBT-006] Refactor: Complex Livewire Component
|
||
- Story: STORY-2025-021
|
||
- Created: Sep 21, 2025
|
||
- Impact: Low - Maintainability concern
|
||
- Effort: Medium (1 day)
|
||
- Priority: P3 - When time permits
|
||
- Description: TaskManager component has 15 methods
|
||
```
|
||
|
||
#### Phase 3: Debt Metrics Calculation
|
||
1. **COUNT** total debt items by category
|
||
2. **SUM** estimated effort (convert to days)
|
||
3. **CALCULATE** debt ratio:
|
||
- Total debt effort / Total development time
|
||
- Percentage of development capacity
|
||
|
||
4. **DISPLAY** debt metrics:
|
||
```
|
||
📊 DEBT METRICS
|
||
══════════════════════════════════
|
||
|
||
Total Debt Items: 24
|
||
Estimated Effort: 32 days
|
||
|
||
By Severity:
|
||
- Critical: 3 items (6 days)
|
||
- Important: 8 items (18 days)
|
||
- Nice to have: 13 items (8 days)
|
||
|
||
By Category:
|
||
- Security debt: 2 items (4 days)
|
||
- Performance debt: 5 items (12 days)
|
||
- Code quality debt: 9 items (10 days)
|
||
- Test debt: 4 items (3 days)
|
||
- Documentation debt: 3 items (2 days)
|
||
- Infrastructure debt: 1 item (1 day)
|
||
|
||
Debt Ratio: 28% of development capacity
|
||
(32 debt days / 115 total development days)
|
||
|
||
Status: ⚠️ High debt load - prioritize reduction
|
||
```
|
||
|
||
#### Phase 4: Impact Assessment
|
||
1. **ANALYZE** user impact:
|
||
- Items affecting user experience
|
||
- Items affecting performance
|
||
- Items invisible to users
|
||
|
||
2. **ANALYZE** developer impact:
|
||
- Items slowing development
|
||
- Items causing confusion
|
||
- Items increasing bug rate
|
||
|
||
3. **ANALYZE** business impact:
|
||
- Items affecting scalability
|
||
- Items increasing costs
|
||
- Items risking compliance
|
||
|
||
4. **DISPLAY** impact assessment:
|
||
```
|
||
⚡ IMPACT ASSESSMENT
|
||
══════════════════════════════════
|
||
|
||
User Impact:
|
||
- 8 items affect user experience
|
||
- 5 items affect performance
|
||
- 11 items are invisible to users
|
||
|
||
Developer Impact:
|
||
- 12 items slow development
|
||
- 7 items cause confusion
|
||
- 9 items increase bug likelihood
|
||
|
||
Business Impact:
|
||
- 4 items affect scalability
|
||
- 3 items increase operational costs
|
||
- 2 items risk compliance/security
|
||
|
||
Risk Level: 🔴 High
|
||
Recommendation: Address critical items immediately
|
||
```
|
||
|
||
#### Phase 5: Priority Matrix Generation
|
||
1. **PLOT** debt items on impact/effort matrix:
|
||
- High impact + Low effort: Quick wins
|
||
- High impact + High effort: Strategic projects
|
||
- Low impact + Low effort: Backlog items
|
||
- Low impact + High effort: Defer or eliminate
|
||
|
||
2. **PRIORITIZE** within each quadrant
|
||
3. **GENERATE** priority recommendations
|
||
|
||
4. **DISPLAY** priority matrix:
|
||
```
|
||
📈 PRIORITY MATRIX
|
||
══════════════════════════════════
|
||
|
||
🎯 HIGH IMPACT + LOW EFFORT (DO FIRST)
|
||
────────────────────────────────────
|
||
[DEBT-002] Memory leak fix (1 day)
|
||
[DEBT-005] Remove unused dependencies (2 hours)
|
||
[DEBT-007] Add missing indexes (4 hours)
|
||
|
||
Total effort: 1.75 days
|
||
Expected impact: High stability, reduced costs
|
||
|
||
📋 HIGH IMPACT + HIGH EFFORT (PLAN & SCHEDULE)
|
||
──────────────────────────────────────────────
|
||
[DEBT-001] Implement data encryption (2 days)
|
||
[DEBT-004] Refactor duplicated logic (3 days)
|
||
[DEBT-008] Migrate to new API version (5 days)
|
||
|
||
Total effort: 10 days
|
||
Expected impact: Security, maintainability
|
||
|
||
⚡ LOW IMPACT + LOW EFFORT (QUICK WINS)
|
||
───────────────────────────────────────
|
||
[DEBT-006] Simplify complex component (1 day)
|
||
[DEBT-009] Update deprecated API calls (2 hours)
|
||
[DEBT-010] Fix linting warnings (1 hour)
|
||
|
||
Total effort: 1.5 days
|
||
Expected impact: Code quality, dev experience
|
||
|
||
⏸️ LOW IMPACT + HIGH EFFORT (DEFER)
|
||
────────────────────────────────────
|
||
[DEBT-011] Achieve 100% test coverage (5 days)
|
||
[DEBT-012] Complete architectural refactor (10 days)
|
||
|
||
Total effort: 15 days
|
||
Recommendation: Defer or break into smaller items
|
||
```
|
||
|
||
#### Phase 6: Debt Story Generation
|
||
1. **GROUP** related debt items
|
||
2. **CREATE** debt reduction story proposals:
|
||
- Story title
|
||
- Combined debt items
|
||
- Total effort estimate
|
||
- Expected value/benefit
|
||
|
||
3. **SUGGEST** story descriptions
|
||
|
||
4. **DISPLAY** debt stories:
|
||
```
|
||
📝 DEBT REDUCTION STORIES
|
||
══════════════════════════════════
|
||
|
||
Suggested Stories to Create:
|
||
|
||
[DEBT-STORY-001] Security Hardening Sprint
|
||
- Combines: DEBT-001, DEBT-013, DEBT-015
|
||
- Items: 3 security issues
|
||
- Effort: 5 days
|
||
- Value: Critical security and compliance
|
||
- Priority: P0 - Must do next sprint
|
||
|
||
[DEBT-STORY-002] Performance Optimization Sprint
|
||
- Combines: DEBT-003, DEBT-007, DEBT-014, DEBT-016
|
||
- Items: 4 performance issues
|
||
- Effort: 6 days
|
||
- Value: 50% faster page loads, better UX
|
||
- Priority: P1 - High value
|
||
|
||
[DEBT-STORY-003] Code Quality Refactor
|
||
- Combines: DEBT-004, DEBT-006, DEBT-017
|
||
- Items: 3 maintainability issues
|
||
- Effort: 5 days
|
||
- Value: Easier maintenance, faster features
|
||
- Priority: P2 - Medium value
|
||
|
||
Create these stories? (y/n)
|
||
```
|
||
|
||
#### Phase 7: Debt Reduction Plan
|
||
1. **ORGANIZE** debt items into sprint-sized chunks
|
||
2. **CREATE** timeline for debt reduction:
|
||
- Immediate: Critical items
|
||
- Short-term: Important items
|
||
- Medium-term: Nice to have items
|
||
- Ongoing: Continuous improvements
|
||
|
||
3. **CALCULATE** capacity allocation:
|
||
- Percentage of sprint for debt work
|
||
- Expected completion timeline
|
||
|
||
4. **DISPLAY** reduction plan:
|
||
```
|
||
📅 DEBT REDUCTION PLAN
|
||
══════════════════════════════════
|
||
|
||
IMMEDIATE (This Week)
|
||
────────────────────────────────
|
||
Sprint Focus: Critical security and stability
|
||
- Fix data encryption (2 days)
|
||
- Patch memory leak (1 day)
|
||
- Add authentication checks (1 day)
|
||
|
||
Total: 4 days
|
||
Team capacity: 2 developers × 2 days each
|
||
|
||
SHORT-TERM (Next 2 Sprints)
|
||
────────────────────────────────
|
||
Sprint 1: Performance optimization
|
||
- Optimize database queries (2 days)
|
||
- Add caching layer (2 days)
|
||
- Add missing indexes (0.5 days)
|
||
|
||
Sprint 2: Code quality improvement
|
||
- Refactor duplicated logic (3 days)
|
||
- Simplify complex components (1 day)
|
||
- Add missing tests (2 days)
|
||
|
||
Total: 10.5 days
|
||
|
||
MEDIUM-TERM (Month 2-3)
|
||
────────────────────────────────
|
||
- Documentation updates (2 days)
|
||
- Dependency upgrades (1 day)
|
||
- Architectural improvements (5 days)
|
||
|
||
Total: 8 days
|
||
|
||
ONGOING PREVENTION
|
||
────────────────────────────────
|
||
- Allocate 20% of each sprint to debt
|
||
- Address new TODOs within 2 weeks
|
||
- Code review checklist for debt
|
||
- Monthly debt review meeting
|
||
|
||
ESTIMATED COMPLETION
|
||
────────────────────────────────
|
||
All critical debt: 1 week
|
||
All high-priority debt: 6 weeks
|
||
All tracked debt: 12 weeks
|
||
|
||
With 20% ongoing capacity: Sustainable
|
||
```
|
||
|
||
#### Phase 8: Trend Analysis
|
||
1. **TRACK** debt over time:
|
||
- New debt created (from recent stories)
|
||
- Debt resolved (from progress logs)
|
||
- Net change
|
||
|
||
2. **CALCULATE** debt velocity:
|
||
- Rate of debt creation
|
||
- Rate of debt resolution
|
||
- Projected timeline
|
||
|
||
3. **DISPLAY** trend analysis:
|
||
```
|
||
📉 DEBT TRENDS
|
||
══════════════════════════════════
|
||
|
||
Last 30 Days:
|
||
- New debt created: 8 items (12 days effort)
|
||
- Debt resolved: 3 items (4 days effort)
|
||
- Net change: +5 items (+8 days) ⚠️
|
||
|
||
Monthly Rate:
|
||
- Debt creation: 8 items/month
|
||
- Debt resolution: 3 items/month
|
||
- Net accumulation: 5 items/month
|
||
|
||
Current Trajectory:
|
||
- At current rate: Debt increasing
|
||
- Projected debt in 3 months: 39 items (56 days)
|
||
- Status: 🔴 Unsustainable
|
||
|
||
With 20% Sprint Capacity (4 days/sprint):
|
||
- Debt resolution: 8 items/month
|
||
- Net change: Even or reducing
|
||
- Clear current debt: 8 sprints (4 months)
|
||
- Status: ✅ Sustainable
|
||
|
||
Recommendation:
|
||
Allocate 20% of sprint capacity to debt reduction
|
||
to prevent accumulation and clear backlog.
|
||
```
|
||
|
||
#### Phase 9: Prevention Recommendations
|
||
1. **ANALYZE** root causes of debt
|
||
2. **SUGGEST** process improvements:
|
||
- Code review additions
|
||
- Definition of done criteria
|
||
- Quality gates
|
||
- Standards enforcement
|
||
|
||
3. **RECOMMEND** preventive measures:
|
||
- Performance budgets
|
||
- Complexity limits
|
||
- Coverage requirements
|
||
- Documentation standards
|
||
|
||
4. **DISPLAY** prevention recommendations:
|
||
```
|
||
🛡️ DEBT PREVENTION
|
||
══════════════════════════════════
|
||
|
||
PROCESS IMPROVEMENTS:
|
||
|
||
Code Review Checklist:
|
||
✓ Add debt check to review template
|
||
✓ Block PRs with new TODO comments
|
||
✓ Require justification for technical debt
|
||
✓ Link debt to tracking story
|
||
|
||
Definition of Done:
|
||
✓ All tests passing
|
||
✓ No new TODO/FIXME comments
|
||
✓ Performance benchmarks met
|
||
✓ Security checks passed
|
||
✓ Documentation updated
|
||
|
||
Quality Gates:
|
||
✓ Automated: Lint, format, test coverage
|
||
✓ Manual: Security review for auth changes
|
||
✓ Manual: Performance review for queries
|
||
|
||
STANDARDS TO ENFORCE:
|
||
|
||
Performance Budgets:
|
||
- Max page load: 2 seconds
|
||
- Max API response: 500ms
|
||
- Max database queries: 10 per request
|
||
- Max N+1 queries: 0
|
||
|
||
Complexity Limits:
|
||
- Max cyclomatic complexity: 10
|
||
- Max method length: 30 lines
|
||
- Max class length: 300 lines
|
||
- Max method parameters: 4
|
||
|
||
Coverage Requirements:
|
||
- Minimum test coverage: 80%
|
||
- All public methods tested
|
||
- Edge cases covered
|
||
- Browser tests for critical paths
|
||
|
||
Documentation Standards:
|
||
- All public APIs documented
|
||
- Complex logic explained
|
||
- Setup instructions complete
|
||
- Deployment process documented
|
||
|
||
TOOL RECOMMENDATIONS:
|
||
|
||
Automated Checks:
|
||
- Laravel Pint for code style
|
||
- Pest for testing
|
||
- PHPStan for static analysis
|
||
- GitHub Actions for CI/CD
|
||
|
||
Monitoring:
|
||
- Laravel Telescope for debugging
|
||
- Performance monitoring
|
||
- Error tracking
|
||
- Log aggregation
|
||
```
|
||
|
||
#### Phase 10: Report Export
|
||
1. **COMPILE** all debt data into comprehensive report
|
||
2. **GENERATE** debt backlog stories
|
||
3. **CREATE** tracking documents
|
||
|
||
4. **OFFER** export options:
|
||
```
|
||
💾 EXPORT OPTIONS
|
||
══════════════════════════════════
|
||
|
||
Export debt report to:
|
||
1. /tech-debt/report-2025-10-01.md
|
||
- Complete debt inventory
|
||
- Metrics and trends
|
||
- Reduction plan
|
||
- Prevention recommendations
|
||
|
||
2. Create debt stories in /docs/stories/backlog/:
|
||
- DEBT-STORY-001.md (Security sprint)
|
||
- DEBT-STORY-002.md (Performance sprint)
|
||
- DEBT-STORY-003.md (Code quality sprint)
|
||
|
||
3. Create debt tracking dashboard:
|
||
- /tech-debt/dashboard.md
|
||
- Updated weekly with latest status
|
||
|
||
Export all? (y/n)
|
||
```
|
||
|
||
5. **DISPLAY** export summary:
|
||
```
|
||
✅ EXPORT COMPLETE
|
||
══════════════════════════════════
|
||
|
||
Files Created:
|
||
✓ /tech-debt/report-2025-10-01.md
|
||
✓ /tech-debt/dashboard.md
|
||
✓ /docs/stories/backlog/DEBT-STORY-001.md
|
||
✓ /docs/stories/backlog/DEBT-STORY-002.md
|
||
✓ /docs/stories/backlog/DEBT-STORY-003.md
|
||
|
||
NEXT STEPS:
|
||
1. Review and prioritize debt stories
|
||
2. Schedule critical items for this sprint
|
||
3. Allocate 20% capacity for debt work
|
||
4. Update debt dashboard weekly
|
||
5. Track debt velocity monthly
|
||
|
||
💡 QUICK START:
|
||
/sdd:story-start DEBT-STORY-001 # Begin security sprint
|
||
```
|
||
|
||
### OUTPUTS
|
||
- Console display of complete debt analysis
|
||
- Optional: `/tech-debt/report-[date].md` - Comprehensive debt report
|
||
- Optional: `/tech-debt/dashboard.md` - Tracking dashboard
|
||
- Optional: `/docs/stories/backlog/DEBT-STORY-*.md` - Debt reduction stories
|
||
|
||
### RULES
|
||
- MUST scan all story directories (not just completed)
|
||
- MUST categorize debt by severity (critical/important/nice-to-have)
|
||
- MUST calculate effort estimates (hours/days)
|
||
- MUST prioritize by impact/effort matrix
|
||
- SHOULD link debt items to source stories
|
||
- SHOULD provide timeline for debt reduction
|
||
- SHOULD suggest prevention measures
|
||
- NEVER modify story files (read-only operation)
|
||
- ALWAYS show debt sources and dates
|
||
- ALWAYS provide actionable recommendations
|
||
- MUST handle missing data gracefully
|
||
|
||
## Debt Severity Levels
|
||
|
||
### Critical (P0)
|
||
- Security vulnerabilities
|
||
- Stability/crash issues
|
||
- Data loss risks
|
||
- Compliance violations
|
||
- **Action**: Fix immediately
|
||
|
||
### Important (P1)
|
||
- Performance degradation
|
||
- Maintainability issues
|
||
- Moderate bug risks
|
||
- User experience problems
|
||
- **Action**: Fix within 1-2 sprints
|
||
|
||
### Nice to Have (P2/P3)
|
||
- Code cleanup
|
||
- Minor refactoring
|
||
- Documentation gaps
|
||
- Optimization opportunities
|
||
- **Action**: Address when capacity allows
|
||
|
||
## Examples
|
||
|
||
### Example 1: All Debt
|
||
```bash
|
||
INPUT:
|
||
/sdd:story-tech-debt
|
||
|
||
OUTPUT:
|
||
→ Scanning all story directories...
|
||
→ Found 24 debt items across 18 stories
|
||
→ Categorizing and prioritizing...
|
||
|
||
🏗️ TECHNICAL DEBT INVENTORY
|
||
══════════════════════════════════
|
||
|
||
🔴 CRITICAL (3 items)
|
||
[DEBT-001] Security: Unencrypted sensitive data
|
||
[DEBT-002] Stability: Memory leak in queue worker
|
||
[DEBT-003] Security: Missing authentication check
|
||
|
||
🟡 IMPORTANT (8 items)
|
||
[DEBT-004] Performance: N+1 query issues
|
||
[DEBT-005] Maintenance: Duplicated business logic
|
||
[... 6 more ...]
|
||
|
||
🟢 NICE TO HAVE (13 items)
|
||
[DEBT-006] Cleanup: Unused dependencies
|
||
[... 12 more ...]
|
||
|
||
[Additional sections...]
|
||
|
||
📝 DEBT REDUCTION STORIES
|
||
|
||
Create 3 debt stories in backlog? (y/n)
|
||
```
|
||
|
||
### Example 2: Critical Debt Only
|
||
```bash
|
||
INPUT:
|
||
/sdd:story-tech-debt critical
|
||
|
||
OUTPUT:
|
||
→ Scanning for critical debt only...
|
||
→ Found 3 critical items
|
||
|
||
🔴 CRITICAL DEBT (3 items, 6 days)
|
||
══════════════════════════════════
|
||
|
||
[DEBT-001] Security: Unencrypted Sensitive Data
|
||
- Story: STORY-2025-012
|
||
- Impact: High - PII at risk
|
||
- Effort: 2 days
|
||
- Description: User data stored without encryption
|
||
|
||
[DEBT-002] Stability: Memory Leak
|
||
- Story: STORY-2025-023
|
||
- Impact: High - Crashes after 24h
|
||
- Effort: 1 day
|
||
- Description: Queue worker memory accumulation
|
||
|
||
[DEBT-003] Security: Missing Auth Check
|
||
- Story: STORY-2025-028
|
||
- Impact: High - Unauthorized access possible
|
||
- Effort: 3 days
|
||
- Description: Admin endpoints lack verification
|
||
|
||
⚠️ ACTION REQUIRED
|
||
──────────────────────────────────
|
||
These critical items should be addressed immediately.
|
||
Estimated effort: 6 days total
|
||
|
||
Create emergency debt story? (y/n)
|
||
```
|
||
|
||
### Example 3: No Debt Found
|
||
```bash
|
||
INPUT:
|
||
/sdd:story-tech-debt
|
||
|
||
OUTPUT:
|
||
→ Scanning all story directories...
|
||
→ Analyzing debt indicators...
|
||
|
||
✅ NO TECHNICAL DEBT DETECTED
|
||
══════════════════════════════════
|
||
|
||
No debt indicators found in stories:
|
||
- No TODO/FIXME comments
|
||
- No deferred items
|
||
- No temporary solutions
|
||
- No skipped tests
|
||
|
||
Status: 🎉 Clean codebase!
|
||
|
||
PREVENTION:
|
||
Continue following best practices:
|
||
- Code review process
|
||
- Test-driven development
|
||
- Performance monitoring
|
||
- Security checks
|
||
|
||
Run /sdd:story-metrics to see quality metrics.
|
||
```
|
||
|
||
## Edge Cases
|
||
|
||
### No Stories Available
|
||
- DETECT empty story directories
|
||
- DISPLAY no data message
|
||
- SUGGEST creating stories first
|
||
- PROVIDE guidance on starting
|
||
|
||
### All Debt Resolved
|
||
- DETECT zero debt items
|
||
- CELEBRATE clean codebase
|
||
- SHOW prevention recommendations
|
||
- SUGGEST ongoing practices
|
||
|
||
### Incomplete Debt Information
|
||
- PARSE flexibly from available data
|
||
- MARK incomplete items for review
|
||
- ESTIMATE effort conservatively
|
||
- CONTINUE with best-effort analysis
|
||
|
||
### Very High Debt Load
|
||
- DETECT debt > 50% of development time
|
||
- DISPLAY warning alert
|
||
- PRIORITIZE ruthlessly (critical only)
|
||
- SUGGEST process intervention
|
||
|
||
## Error Handling
|
||
- **No story directories**: Report missing structure, suggest `/sdd:project-init`
|
||
- **Permission errors**: Report specific file access issues
|
||
- **Malformed story files**: Skip problematic files, log warnings
|
||
- **Invalid priority parameter**: Show valid options, use default
|
||
- **Export directory conflicts**: Ask to overwrite or merge
|
||
|
||
## Performance Considerations
|
||
- Efficient file scanning (single pass per directory)
|
||
- Lazy parsing (only parse when needed)
|
||
- Pattern matching with regex for debt indicators
|
||
- Streaming output for large debt lists
|
||
- Typical completion time: < 3 seconds for 50 stories
|
||
|
||
## Related Commands
|
||
- `/sdd:story-metrics` - Development velocity and quality metrics
|
||
- `/sdd:story-patterns` - Identify recurring patterns
|
||
- `/sdd:project-status` - Current project state
|
||
- `/sdd:story-new [id]` - Create debt reduction story
|
||
|
||
## Constraints
|
||
- ✅ MUST be read-only (no story modifications)
|
||
- ✅ MUST categorize by severity (critical/important/nice-to-have)
|
||
- ✅ MUST provide effort estimates
|
||
- ⚠️ SHOULD link debt to source stories
|
||
- 📊 SHOULD include impact assessment
|
||
- 💡 SHOULD generate reduction plan
|
||
- 🛡️ SHOULD suggest prevention measures
|
||
- ⏱️ MUST complete analysis in reasonable time (< 5s)
|
||
- 📁 SHOULD offer to export and create stories
|