kjh2064/KArtSell.Aegis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5e50ec699133fecdde9a1b502ff11f928c50ab4c
KArtSell.Aegis/TECH_DEBT_REGISTER.md
T
kjh2064 5e50ec6991
ci / backend (push) Failing after 1s
Details
ci / static (push) Failing after 5s
Details
ci / frontend (push) Failing after 5s
Details
docs: Enhance document routing and create tech debt registry (PR 3a) 
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>
2026-08-02 05:44:47 +09:00

3.7 KiB
Raw Blame History

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
  • Tracking: CLAUDE.md
  • Decision Log: See individual PR commit messages and ADRs
Reference in New Issue View Git Blame Copy Permalink