| # Tech Debt & Bug Fix Specs |
|
|
| **Status:** AWAITING SENIOR REVIEW |
| **Created:** 2025-12-06 |
|
|
| --- |
|
|
| ## Overview |
|
|
| These specs consolidate all identified bugs, tech debt, and architectural issues into phased, implementable work packages. Each spec is designed to be a single PR with TDD, SOLID, DRY, Gang of Four principles. |
|
|
| **Implementation Order:** SPEC-20 → SPEC-21 → SPEC-22 |
|
|
| --- |
|
|
| ## Spec Index |
|
|
| | Spec | Title | Priority | Effort | Status | |
| |------|-------|----------|--------|--------| |
| | [SPEC-20](./SPEC-20-PUBMED-JSON-FIX.md) | PubMed JSON Parsing Fix | P2 | 15 min | READY | |
| | [SPEC-21](./SPEC-21-MIDDLEWARE-ARCHITECTURE.md) | Middleware Architecture Refactor | P2 | 2 hours | READY | |
| | [SPEC-22](./SPEC-22-PROGRESS-BAR-REMOVAL.md) | Progress Bar Removal | P3 | 15 min | READY | |
|
|
| **Total Effort:** ~2.5 hours |
|
|
| --- |
|
|
| ## Why This Order? |
|
|
| ### SPEC-20 First (15 min) |
| - Quickest win |
| - Fixes a real crash bug |
| - Builds confidence before larger refactor |
| - Single file, single PR |
|
|
| ### SPEC-21 Second (2 hours) |
| - The big architectural fix |
| - Renames confusing folder |
| - Implements proper MS framework patterns |
| - Fixes HuggingFace retry bug THE RIGHT WAY |
| - Adds token tracking |
|
|
| ### SPEC-22 Last (15 min) |
| - Cosmetic only |
| - Can be deferred if needed |
| - Easy cleanup |
|
|
| --- |
|
|
| ## What These Specs Consolidate |
|
|
| These specs replace the scattered documentation in: |
|
|
| | Old Location | Now Covered By | |
| |--------------|----------------| |
| | `docs/bugs/p2-hardening-issues.md` Issue 1 | SPEC-20 | |
| | `docs/bugs/p2-hardening-issues.md` Issue 2 | SPEC-21 | |
| | `docs/architecture/adr-001-middleware-refactor.md` | SPEC-21 | |
| | `docs/bugs/p3-progress-bar-positioning.md` | SPEC-22 | |
|
|
| --- |
|
|
| ## What's NOT In These Specs (Deferred P3) |
|
|
| The following are documented but deferred for later: |
|
|
| 1. **OpenTelemetry observability** - Nice to have, not blocking |
| 2. **Thread state serialization** - Nice to have, not blocking |
| 3. **ResearchMemory locks** - Not a bug today (sequential execution) |
| 4. **Error path cleanup** - Minor resource leakage, GC handles it |
| 5. **Per-tool configuration** - Nice to have |
| 6. **Context provider lifecycle** - Nice to have |
|
|
| These remain documented in `docs/bugs/p3-ms-framework-gaps.md` for future work. |
|
|
| --- |
|
|
| ## Implementation Protocol |
|
|
| For each spec: |
|
|
| 1. **Read the spec** - Understand the problem and solution |
| 2. **TDD** - Write failing test first |
| 3. **Implement** - Minimal code to pass tests |
| 4. **Run `make check`** - Lint + typecheck + test |
| 5. **Commit** - Single commit per spec |
| 6. **PR** - One PR per spec with spec number in title |
|
|
| --- |
|
|
| ## Commit Message Format |
|
|
| ``` |
| fix: PubMed JSON parsing (SPEC-20) |
| |
| Moves JSON parsing inside try/except block to handle API |
| maintenance pages gracefully. Adds JSONDecodeError handling. |
| |
| Fixes: production crash on PubMed maintenance pages |
| ``` |
|
|
| ``` |
| refactor: middleware architecture (SPEC-21) |
| |
| - Renames src/middleware → src/workflows (accurate naming) |
| - Creates proper src/middleware with ChatMiddleware implementations |
| - Implements RetryMiddleware (fixes HuggingFace 429 crashes) |
| - Implements TokenTrackingMiddleware (enables cost monitoring) |
| ``` |
|
|
| ``` |
| fix: remove progress bar overlap (SPEC-22) |
| |
| Removes gr.Progress() from research_agent function. |
| Gradio's Progress is incompatible with ChatInterface. |
| Emoji status messages in chat output are retained. |
| ``` |
|
|
| --- |
|
|
| ## Senior Review Checklist |
|
|
| Before implementation, please verify: |
|
|
| - [ ] SPEC-20: Fix approach is correct (move into try/except) |
| - [ ] SPEC-21: MS middleware pattern is used correctly |
| - [ ] SPEC-21: RetryMiddleware implementation follows framework conventions |
| - [ ] SPEC-21: Folder rename won't break anything else |
| - [ ] SPEC-22: Removing gr.Progress() is the right fix (vs CSS hack) |
| - [ ] Order of implementation makes sense |
| - [ ] Nothing critical is missing from these specs |
|
|
| --- |
|
|
| ## After Implementation |
|
|
| Once all specs are implemented: |
|
|
| 1. Archive old docs: |
| - `docs/bugs/p2-hardening-issues.md` → Mark as RESOLVED |
| - `docs/architecture/adr-001-middleware-refactor.md` → Delete or archive |
| - `docs/bugs/p3-progress-bar-positioning.md` → Mark as RESOLVED |
|
|
| 2. Update `docs/bugs/active-bugs.md` to reflect completed fixes |
|
|
| 3. Consider v0.2.0 release with these fixes |
|
|
