| # Technical Debt Registry | |
| > **Last Updated**: 2025-12-06 | |
| This document tracks all known technical debt items in the DeepBoner codebase. | |
| ## Summary Dashboard | |
| | Category | Open | In Progress | Resolved | | |
| |----------|------|-------------|----------| | |
| | Architecture | 2 | 0 | 0 | | |
| | Code Quality | 4 | 0 | 0 | | |
| | Testing | 2 | 0 | 0 | | |
| | Documentation | 2 | 0 | 0 | | |
| | Performance | 2 | 0 | 0 | | |
| | Dependencies | 1 | 0 | 0 | | |
| | **Total** | **13** | **0** | **0** | | |
| --- | |
| ## Architecture | |
| ### DEBT-001: Reserved but Empty Directories | |
| **Category:** Architecture | |
| **Severity:** Low | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| `src/database_services/` and `src/retrieval_factory/` exist but are empty placeholders for future features. | |
| **Impact:** | |
| - Confusion about project structure | |
| - Empty imports may cause issues | |
| **Current Workaround:** | |
| Document as "reserved" in component inventory. | |
| **Proposed Solution:** | |
| Either implement the features or remove the directories. | |
| **Effort Estimate:** S | |
| --- | |
| ### DEBT-002: Experimental LangGraph Orchestrator | |
| **Category:** Architecture | |
| **Severity:** Medium | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| `src/orchestrators/langgraph_orchestrator.py` is marked as experimental and may not be fully tested or integrated. | |
| **Impact:** | |
| - Unclear which orchestrator is preferred | |
| - May have untested edge cases | |
| - Maintenance burden of two orchestrators | |
| **Current Workaround:** | |
| Default to AdvancedOrchestrator in production. | |
| **Proposed Solution:** | |
| Either promote to production status with full testing, or deprecate and remove. | |
| **Effort Estimate:** M | |
| --- | |
| ## Code Quality | |
| ### DEBT-003: Complex Orchestrator Logic | |
| **Category:** Code Quality | |
| **Severity:** Medium | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| `src/orchestrators/advanced.py` has complex branching logic that required disabling pylint rules (PLR0912, PLR0913). | |
| **Impact:** | |
| - Difficult to understand and maintain | |
| - Higher bug risk | |
| - Harder to test comprehensively | |
| **Current Workaround:** | |
| Suppressed linter warnings with explicit ignores. | |
| **Proposed Solution:** | |
| Refactor into smaller, focused methods. Consider command pattern for orchestration steps. | |
| **Effort Estimate:** L | |
| --- | |
| ### DEBT-004: Magic Numbers in Code | |
| **Category:** Code Quality | |
| **Severity:** Low | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| Some statistical constants and thresholds are hardcoded (e.g., p-values, score thresholds), requiring PLR2004 ignore. | |
| **Impact:** | |
| - Difficult to tune parameters | |
| - Magic numbers obscure intent | |
| **Current Workaround:** | |
| Documented with comments where used. | |
| **Proposed Solution:** | |
| Move to configuration or constants module with documentation. | |
| **Effort Estimate:** S | |
| --- | |
| ### DEBT-005: Global Singleton Pattern | |
| **Category:** Code Quality | |
| **Severity:** Low | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| Settings uses a singleton pattern (`settings = get_settings()`), requiring PLW0603 ignore. | |
| **Impact:** | |
| - Harder to test with different configurations | |
| - Global state can cause issues | |
| **Current Workaround:** | |
| Test fixtures override settings. | |
| **Proposed Solution:** | |
| Consider dependency injection for settings, especially in tests. | |
| **Effort Estimate:** M | |
| --- | |
| ### DEBT-006: ClinicalTrials Uses requests Instead of httpx | |
| **Category:** Code Quality | |
| **Severity:** Low | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| `src/tools/clinicaltrials.py` uses `requests` library while rest of codebase uses `httpx` because ClinicalTrials.gov WAF blocks httpx. | |
| **Impact:** | |
| - Inconsistent HTTP client usage | |
| - Two libraries for same purpose | |
| **Current Workaround:** | |
| Documented in code comments and pyproject.toml. | |
| **Proposed Solution:** | |
| 1. Investigate httpx headers/options that work with WAF | |
| 2. Or accept this as necessary divergence and document | |
| **Effort Estimate:** M | |
| --- | |
| ## Testing | |
| ### DEBT-007: Integration Tests Require Real APIs | |
| **Category:** Testing | |
| **Severity:** Medium | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| Integration tests marked with `@pytest.mark.integration` make real API calls, which can be slow and flaky. | |
| **Impact:** | |
| - Slow CI runs | |
| - Flaky tests due to network issues | |
| - Rate limit risks | |
| **Current Workaround:** | |
| Integration tests are not run in CI by default. | |
| **Proposed Solution:** | |
| 1. Use VCR-style recording for reproducible tests | |
| 2. Set up isolated test environment | |
| 3. Better mock infrastructure for external APIs | |
| **Effort Estimate:** L | |
| --- | |
| ### DEBT-008: Incomplete E2E Test Coverage | |
| **Category:** Testing | |
| **Severity:** Medium | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| End-to-end tests exist but don't cover all user scenarios, especially error paths. | |
| **Impact:** | |
| - Production bugs may not be caught in testing | |
| - Edge cases untested | |
| **Current Workaround:** | |
| Manual testing before releases. | |
| **Proposed Solution:** | |
| Expand E2E test suite with more scenarios, especially: | |
| - Error handling | |
| - Rate limit recovery | |
| - Multiple iterations | |
| **Effort Estimate:** L | |
| --- | |
| ## Documentation | |
| ### DEBT-009: Outdated Inline Comments | |
| **Category:** Documentation | |
| **Severity:** Low | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| Some code comments may reference old architecture or removed features from rapid hackathon development. | |
| **Impact:** | |
| - Confusion when reading code | |
| - Comments don't match implementation | |
| **Current Workaround:** | |
| None - requires manual review. | |
| **Proposed Solution:** | |
| Systematic review of comments during code review process. | |
| **Effort Estimate:** M | |
| --- | |
| ### DEBT-010: Missing API Documentation | |
| **Category:** Documentation | |
| **Severity:** Low | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| No formal API documentation (e.g., Sphinx-generated) for public interfaces. | |
| **Impact:** | |
| - Developers must read source code | |
| - Hard to know public vs internal APIs | |
| **Current Workaround:** | |
| Docstrings in code serve as documentation. | |
| **Proposed Solution:** | |
| Consider generating API docs with Sphinx or mkdocs. | |
| **Effort Estimate:** M | |
| --- | |
| ## Performance | |
| ### DEBT-011: Model Loading on First Request | |
| **Category:** Performance | |
| **Severity:** Low | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| Sentence-transformers model is loaded on first query, causing slow initial response. | |
| **Impact:** | |
| - First query takes 30+ seconds | |
| - Poor user experience on first use | |
| **Current Workaround:** | |
| Docker pre-downloads the model during build. | |
| **Proposed Solution:** | |
| 1. Pre-warm model on application startup | |
| 2. Or accept cold start with loading indicator | |
| **Effort Estimate:** S | |
| --- | |
| ### DEBT-012: No Connection Pooling | |
| **Category:** Performance | |
| **Severity:** Low | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| External API calls may not fully utilize connection pooling. | |
| **Impact:** | |
| - Slower requests due to connection overhead | |
| - Higher latency under load | |
| **Current Workaround:** | |
| httpx AsyncClient provides some pooling. | |
| **Proposed Solution:** | |
| Audit and optimize connection handling for external APIs. | |
| **Effort Estimate:** S | |
| --- | |
| ## Dependencies | |
| ### DEBT-013: Pinned Beta Dependencies | |
| **Category:** Dependencies | |
| **Severity:** Medium | |
| **Added:** 2025-12-06 | |
| **Status:** Open | |
| **Description:** | |
| `agent-framework-core==1.0.0b*` is a beta release, pinned to avoid breaking changes. | |
| **Impact:** | |
| - May miss bug fixes and improvements | |
| - Beta software may have stability issues | |
| **Current Workaround:** | |
| Version pinning with explicit documentation. | |
| **Proposed Solution:** | |
| 1. Monitor for stable release | |
| 2. Upgrade and test when 1.0.0 releases | |
| 3. Add integration tests specific to agent framework | |
| **Effort Estimate:** M | |
| --- | |
| ## Resolved Items | |
| *No items resolved yet.* | |
| --- | |
| ## How to Update This Registry | |
| ### Adding Items | |
| 1. Create new section with next DEBT-XXX number | |
| 2. Fill in all fields | |
| 3. Update summary dashboard | |
| ### Resolving Items | |
| 1. Change status to "Resolved" | |
| 2. Add resolution notes | |
| 3. Move to "Resolved Items" section | |
| 4. Update summary dashboard | |
| ### Review Schedule | |
| - Weekly: Triage new items | |
| - Sprint: Plan debt reduction | |
| - Monthly: Review progress | |