A newer version of the Gradio SDK is available:
6.1.0
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:
- Investigate httpx headers/options that work with WAF
- 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:
- Use VCR-style recording for reproducible tests
- Set up isolated test environment
- 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:
- Pre-warm model on application startup
- 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:
- Monitor for stable release
- Upgrade and test when 1.0.0 releases
- Add integration tests specific to agent framework
Effort Estimate: M
Resolved Items
No items resolved yet.
How to Update This Registry
Adding Items
- Create new section with next DEBT-XXX number
- Fill in all fields
- Update summary dashboard
Resolving Items
- Change status to "Resolved"
- Add resolution notes
- Move to "Resolved Items" section
- Update summary dashboard
Review Schedule
- Weekly: Triage new items
- Sprint: Plan debt reduction
- Monthly: Review progress