# 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