# {{title}}

**Type:** enhancement  
**Status:** todo  
**Branch:** refactor/{{scope}}-{{slug}} (or `perf/` | `chore/` as appropriate)  
**Linked roadmap section:** {{phase}}

---

## 🧠 Context
{{what exists and why change}}

## 🎯 Goal
{{improve reliability/maintainability/performance/devex}}

## 📏 Success Metrics
- [ ] {{metric}} (baseline: {{value}} → target: {{value}})

## 🧩 Acceptance Criteria
- [ ] No behavior regressions (characterization tests if needed)
- [ ] Tests updated/added to reflect new contracts
- [ ] Documentation updated (architecture notes, ADR if architectural)
- [ ] CHANGELOG entry added

## 🛠️ Implementation Outline
1. Create/switch to branch `refactor/{{scope}}-{{slug}}`
2. Add characterization tests (if legacy)
3. Apply patterns (e.g., Strategy/Adapter/Factory/Builder) where they reduce coupling
4. Simplify and document public interfaces
5. Update docs and examples
6. Move this file to `in_progress/` then `done/`
7. Create PR referencing this issue

## 🔍 Alternatives Considered
- {{option}} → {{tradeoffs}}

## ⚠️ Risks / Mitigations
- {{risk}} → {{mitigation}}

## 🔗 Discussion Notes
{{from exploration}}


