Technical Debt
This directory tracks known debt and audit checklists for the repository.
Current Status
0 active debt items.
All resolved debt items live in docs/_archive/debt/.
Recently Archived (2026-01-21)
| ID |
Title |
Status |
| DEBT-043 |
SRP — Reduce "God Files" (≤400 LoC ceiling) |
✅ Resolved |
| DEBT-047 |
Magic Numbers — Extract Policy-Encoding Literals to Constants |
✅ Resolved |
| DEBT-039 |
Broad Exception Catches Throughout Codebase |
✅ Resolved |
| DEBT-044 |
DRY — Remove Duplicated CLI Boilerplate |
✅ Resolved |
| DEBT-045 |
Complexity — Remove # noqa: PLR0912/PLR0915 Methods |
✅ Resolved |
| DEBT-046 |
Dependency Inversion — Introduce a Kalshi Client Factory |
✅ Resolved |
Recently Archived (2026-01-19)
| ID |
Title |
Status |
| DEBT-041 |
SPEC-030 Has Unchecked Acceptance Criteria |
✅ Resolved |
| DEBT-038 |
Orchestrator Escalation Logic Not Implemented |
✅ Resolved |
| DEBT-042 |
Unused API Client Methods |
✅ Resolved (SPEC-043) |
| DEBT-040 |
Unused Synthesizer Cost/Token Tracking Methods |
✅ Resolved |
| DEBT-034 |
Broad Exception Catches in Agent/Execution Code |
✅ Resolved |
| DEBT-037 |
MockSynthesizer in Production Path |
✅ Resolved (SPEC-042) |
| DEBT-033 |
Frozen Pydantic Model object.__setattr__ Hack |
✅ Closed (False Positive) |
| DEBT-035 |
Missing Agent Integration Tests |
✅ Resolved |
| DEBT-036 |
Deep Research Timeout Hardcoded |
✅ Resolved |
Recently Archived (2026-01-18)
| ID |
Title |
Status |
| DEBT-031 |
Floor Division in P&L Statistics |
✅ Archived |
| DEBT-032 |
Midpoint Rounding Inconsistency |
✅ Archived |
Recently Archived (2026-01-17)
| ID |
Title |
Status |
| DEBT-014 |
Friction Residuals - Research Pipeline & Agent Design |
✅ Archived |
| DEBT-025 |
Subpenny Pricing Strategy (FixedPointDollars → rounding policy) |
✅ Archived |
Recently Archived (2026-01-16)
| ID |
Title |
Status |
| DEBT-030 |
Trading Fees Missing from P&L (Must Use Settlement Records) |
✅ Resolved |
| DEBT-029 |
Settlement-as-Synthetic-Fill Reconciliation (Professional P&L) |
✅ Implemented |
Previously Resolved (2026-01-16)
| ID |
Title |
Status |
| DEBT-018 |
Test SSOT Stabilization (Fixtures, Mocks, Exa Coverage) |
✅ Resolved |
| DEBT-016 |
Automate Fixture Drift Detection + Weekly Re-Recording |
✅ Resolved |
| DEBT-015 |
Missing API Endpoints - 50/74 (68%) |
✅ Complete (remaining blocked/institutional) |
| DEBT-028 |
API Schema Drift - January 2026 Migration |
✅ Verified Working |
Next ID Tracker
Use this ID for the next debt item:
DEBT-048
Files
| File |
Purpose |
code-audit-checklist.md |
Periodic audit checklist / runbook (reference doc) |
Archived Reference Docs
These are still useful references, but were moved under the archive during consolidation:
docs/_archive/debt/technical-debt.md - Living register with historical contextdocs/_archive/debt/security-audit.md - Security findings (agent safety, injection risks)
Archived Source Documents (2026-01-11)
The following documents were consolidated into DEBT-014 and archived:
| Document |
Archive Location |
Notes |
friction.md |
_archive/debt/friction.md |
User friction log - all items captured in DEBT-014 |
hacks.md |
_archive/debt/hacks.md |
Hacky implementations - all P1/P2 items in DEBT-014 |
backwards-compatibility.md |
_archive/debt/backwards-compatibility.md |
Compat code inventory - all items in DEBT-014 |
bloat.md |
_archive/debt/bloat.md |
Bloat analysis - fully resolved (DEBT-008/009/010) |
Workflow
- Add new debt as a short, actionable entry (priority + impact + fix path).
- Link to the relevant bug (
docs/_bugs/) or spec/future item (docs/_specs/, docs/_future/) when applicable.
- When resolved, move the entry to the Resolved section (don't delete history).
Archive (Resolved)
All resolved debt items are stored in
docs/_archive/debt/.
Recently Resolved (Ralph Wiggum Cleanup - 2026-01-09)
| ID |
Title |
Status |
| DEBT-003 |
Loose DB Transactions (session.begin() pattern) |
✅ Complete |
| DEBT-002 |
Magic Numbers Analysis (Phase 1 comments) |
✅ Complete |
| DEBT-001 |
API Client Typing (Pydantic models for portfolio) |
✅ Complete |
Recently Resolved (2026-01-10)
| ID |
Title |
Status |
| DEBT-012 |
Exa pipeline error observability (missing trace context) |
✅ Complete |
| DEBT-011 |
Unbounded disk growth (DB snapshots, logs, caches) |
✅ Complete |
| DEBT-008 |
Dead Code Cleanup (True Slop) |
✅ Complete |
| DEBT-010 |
Reduce Boilerplate & Structural Bloat |
✅ Complete |
| DEBT-009 |
Finish Halfway Implementations |
✅ Complete |
| DEBT-007 |
A+ Engineering Robustness Delta (Operational Hardening Gaps) |
✅ Complete |
Recently Resolved (2026-01-11)
| ID |
Title |
Status |
| DEBT-013 |
Category filtering SSOT: use /events (avoid /markets pagination traps) |
✅ Complete |
Recently Resolved (2026-01-13)
| ID |
Title |
Status |
| DEBT-017 |
Model Architecture Cleanup (Duplicate Order Models + Validation Gaps) |
✅ Complete |
| DEBT-019 |
Exa Empty publishedDate Validation Bug |
✅ Complete |
| DEBT-020 |
Kalshi Market Discovery Gaps (false positive / user error) |
✅ Closed |
| DEBT-022 |
Exa Research Task Recovery (list_research_tasks() crash recovery) |
✅ Complete |
| DEBT-023 |
Production Maturity Gaps (Senior Engineer Audit) |
✅ Complete (Reference Doc) |
| DEBT-024 |
CLI exit code policy (not found vs empty results) |
✅ Complete |
Recently Resolved (2026-01-14)
| ID |
Title |
Status |
| DEBT-026 |
Missing Function Docstrings |
✅ Complete |
| DEBT-027 |
Private Function Docstrings |
✅ Complete |
Debt Transitions (Historical)
None. All debt items resolved or elevated to specs.
| Item |
Resolution |
Date |
| DEBT-004 |
Implemented via SPEC-027 |
2026-01-09 |
| DEBT-002 Phase 2-3 |
Closed as "Won't Fix" (see docs/_archive/debt/technical-debt.md) |
2026-01-09 |