1 files changed, 56 insertions, 0 deletions
diff --git a/docs/development/refactor-roadmap.md b/docs/development/refactor-roadmap.md
new file mode 100644
index 0000000..eeee879
--- /dev/null
+++ b/docs/development/refactor-roadmap.md
@@ -0,0 +1,56 @@
+# Refactor Roadmap (Prioritized)
+
+## Priorities
+- P0 (now): safety, compatibility, correctness
+- P1 (next): validation, observability, developer UX
+- P2 (later): performance, async, resiliency
+
+## P0 — Immediate
+- Stabilize transport: keep `_get_payload(include_empty_path)`; special-case `config-file`
+- Keep shims: `pyvyos/device.py` and `pyvyos/rest.py` re-export from `pyvyos/core/*`
+- Typed exceptions: introduce `SDKError`, `HttpError`, `ApiError`, `ValidationError`
+- Timeouts: ensure sane defaults, expose in `VyDevice`
+- Logging: centralize in transport, structured key fields (op, command, status)
+- Tests: payload assertions for `config-file` (path: []), regression for others
+- Docs: architecture and path rules (done)
+
+## P1 — Short Term
+- Specs (optional): Pydantic models in `pyvyos/specs/commands/*`
+- `utils/`: path builders, request_id, safe_json redaction
+- Deprecation policy: note in README; warn on internal imports (future only)
+- CI: test matrix (Python 3.13), codecov, lint (ruff/flake8), type-check (pyright/mypy)
+- Release: conventional commits + CHANGELOG; ensure tags push
+- Docs: contributor guide, release playbook (short)
+
+## P2 — Medium Term
+- Async client: `AsyncRestClient` (aiohttp/httpx), opt-in
+- Retries & backoff: idempotent ops only; circuit-breaker (future)
+- Rate limiting: client-side token bucket (opt-in)
+- Caching: read-only `show/retrieve` (TTL) optional
+- Batch ops: smarter `configure_multiple_op` planning
+
+## Migration & Compatibility
+- Public API: `from pyvyos import VyDevice, ApiResponse` (stable)
+- Internal: prefer `pyvyos.core.*` for new code
+- Shims stay until 1.0.0; removal at next major only
+
+## Testing Plan
+- Unit: transport (errors, timeouts), domain (paths)
+- Contract: sample JSON fixtures per command
+- E2E: optional job against a test VyOS (gated, non-blocking)
+
+## Release Flow (lean)
+- Branch: feature → PR → squash merge
+- Pre-release (optional): `-rcX` tags
+- Tag + publish: GitHub Action (uv build + PyPI publish)
+
+## Risks & Mitigations
+- Hidden breakages → keep shims, add regression tests
+- API drift (VyOS) → specs folder eases updates
+- Logging noise → default INFO; debug gated via env
+- Security → default `verify=True`, redact secrets in logs
+
+## Success Criteria
+- 0.3.x users unaffected
+- New structure adopted by contributors
+- Lower maintenance overhead (fewer regressions)