File size: 4,178 Bytes
2ac49c3 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 |
# 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
|