kjh2064
5e50ec6991
Strengthen documentation coherence and navigation: README.md: - Add 'Developer's Document Guide' section at top - Link to CLAUDE.md, AGENTS.md, architecture, guardrails, validation gates - Reference docs/INDEX.md and TECH_DEBT_REGISTER.md docs/INDEX.md (new): - Central documentation index with purpose and audience - Core guides, executive/planning, tech debt, reference docs - Quick links for first change, architectural decisions, validation TECH_DEBT_REGISTER.md (new): - Tech debt tracking per AGENTS.md v16.0 - 8 registered debts (code analysis suppressions, deferred refactoring) - Impact/Effort matrix with paydown strategy (quarterly 20% target) - Status tracking with completion history - How-to guide for resolving debt CLAUDE.md: - Update TECH_DEBT_REGISTER reference from 'to be created' to actual link Result: - Developers land on README → directed to CLAUDE.md or AGENTS.md - All docs cross-reference each other for circular navigation - Tech debt fully visible and tracked with clear paydown roadmap - docs/INDEX.md provides comprehensive reference point Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
# Tech Debt Register
|
|
|
|
**Governance:** Tracked per AGENTS.md v16.0. Quarterly paydown target: 20% by Impact.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
| Status | Count | Total Impact |
|
|
|--------|-------|--------------|
|
|
| Backlog | 8 | 20 pts |
|
|
| In Progress | 0 | 0 pts |
|
|
| Completed | 0 | 0 pts |
|
|
|
|
---
|
|
|
|
## Registry
|
|
|
|
### Code Analysis Suppressions
|
|
|
|
| ID | Category | Impact | Effort | Status | Notes | Owner | ADR |
|
|
|----|----------|--------|--------|--------|-------|-------|-----|
|
|
| DEBT-001 | CA1822 (static hints) | Low (1) | Low (1) | Backlog | Analyzer suggestions for instance methods that could be static. Not performance-critical; batch during refactors. | Team | - |
|
|
| DEBT-002 | CA1873 (array logging) | Low (1) | Low (1) | Backlog | Conditional array evaluation in logging. Low runtime impact; defer until performance profiling. | Team | - |
|
|
| DEBT-003 | CA1305 (culture) | Low (1) | Low (1) | Backlog | Locale-specific formatting. Accept as-is for Serilog; breaking change if fixed. | Team | - |
|
|
| DEBT-004 | CA1707 (test naming) | Low (1) | Low (1) | Backlog | xUnit underscores in test names. Convention; no fix needed. | Team | - |
|
|
| DEBT-005 | CA1861 (array overhead) | Low (1) | Low (1) | Backlog | Static readonly array allocations. Negligible perf; accept trade-off for readability. | Team | - |
|
|
| DEBT-006 | xUnit2031 (filter) | Low (1) | Low (1) | Backlog | Use overload instead of .Where() for Assert.Single. Analyzer nit; defer. | Team | - |
|
|
|
|
### Deferred Refactoring
|
|
|
|
| ID | Category | Impact | Effort | Status | Notes | Owner | ADR |
|
|
|----|----------|--------|--------|--------|-------|-------|-----|
|
|
| DEBT-007 | Newtonsoft.Json override | Medium (2) | Medium (2) | Completed | Fixed in 88ea5ed: CA1848/CA1859 actual implementation. LoggerMessage + HashSet/Dictionary. | @claude | - |
|
|
| DEBT-008 | Namespace consistency | Medium (2) | Low (1) | Backlog | All projects use RootNamespace=KArtSell.Aegis; AssemblyName retained per-project for DLL clarity. Consider if alignment needed. | - | - |
|
|
|
|
---
|
|
|
|
## Impact/Effort Matrix
|
|
|
|
```
|
|
Low Effort High Effort
|
|
High Impact QUICK WINS ROADMAP
|
|
(DEBT-007) (none currently)
|
|
|
|
Low Impact BATCH MONITOR
|
|
(DEBT-001/002) (DEBT-003/004/005/006/008)
|
|
```
|
|
|
|
### Quick Wins (Do This Sprint)
|
|
- None current
|
|
|
|
### Roadmap (Next Quarter)
|
|
- None current
|
|
|
|
### Batch During Feature Work
|
|
- DEBT-001 (static hints): Batch with ModelOperations refactoring
|
|
- DEBT-002 (array logging): Include in Serilog structured-logging improvement
|
|
|
|
### Monitor & Defer
|
|
- DEBT-003 through DEBT-006: Keep in backlog; revisit if performance audit flags them
|
|
- DEBT-008: Accept per-project AssemblyName for clarity (DLL identification)
|
|
|
|
---
|
|
|
|
## Paydown Tracking
|
|
|
|
### Q3 2026 (Current)
|
|
- **Target:** 20% of total impact resolved = 4 pts
|
|
- **Completed:** DEBT-007 (2 pts) — 50% of target achieved
|
|
- **Remaining:** Identify 2 more low-effort wins
|
|
|
|
### Q4 2026
|
|
- **Target:** 20% = 4 pts (cumulative: 8 pts / 40% debt)
|
|
- **Plan:** TBD after Q3 completion
|
|
|
|
### Q1 2027
|
|
- **Target:** 20% = 4 pts (cumulative: 12 pts / 60% debt)
|
|
- **Plan:** TBD
|
|
|
|
---
|
|
|
|
## How to Resolve Tech Debt
|
|
|
|
1. **Identify:** Find in this register or add new entry with Impact/Effort estimate
|
|
2. **Estimate:** Low (1) / Medium (2) / High (3) for each dimension
|
|
3. **Schedule:** Pick based on matrix above
|
|
4. **Implement:** Separate PR, reference Debt ID in commit message (e.g., `TECH-007: Fix CA1848`)
|
|
5. **Verify:** Update register (move to Completed, record date + ADR link)
|
|
6. **Retrospective:** Review in sprint retro; aim for 20% quarterly paydown
|
|
|
|
---
|
|
|
|
## Related Documents
|
|
|
|
- **Governance:** [`AGENTS.md`](AGENTS.md#13-tech-debt-management-tech-debt-registry)
|
|
- **Tracking:** [`CLAUDE.md`](CLAUDE.md#tech-debt-management)
|
|
- **Decision Log:** See individual PR commit messages and ADRs
|