async sqlmodel

docs/skills/fastapi-async-sqlalchemy-modernization/SKILL.md

@@ -62,6 +62,9 @@ Use these concepts as the planning backbone:
 7. Observability and resilience:
    Add pool/connection settings, logging, timeout, and health checks as first-class plan items.
    See the [observability reference](references/observability.md).
+8. SQLModel adoption where appropriate:
+   Prefer SQLModel for typed ORM models and API-facing data models when it reduces duplication, while preserving SQLAlchemy async lifecycle patterns.
+   See the [SQLModel integration reference](references/sqlmodel.md).
 
 ### Concept Reference Map
 
@@ -74,6 +77,7 @@ Use these concepts as the planning backbone:
 | Dependency injection | [Session management reference](references/session.md) |
 | Implicit I/O control in ORM | [Implicit I/O reference](references/implicit_io.md) |
 | Observability and resilience | [Observability reference](references/observability.md) |
+| SQLModel adoption where appropriate | [SQLModel integration reference](references/sqlmodel.md) |
 
 ## Decision Points
 
@@ -85,6 +89,7 @@ Use these branching decisions before proposing migration steps.
 | ORM usage | Already ORM 2.x style (`select`, `session.execute`) | Legacy Query API: add compatibility stage and refactor incrementally |
 | Session scope | Request-scoped already | Global/shared sessions found: prioritize session-scope fix first |
 | Lifespan | Existing FastAPI lifespan hook | No lifespan hook: introduce lifespan before broader DB changes |
+| Model layer | Existing SQLModel models fit roadmap | SQLAlchemy-only models: evaluate SQLModel adoption by bounded module |
 | Concurrency | Background jobs/tasks use DB | No background DB use |
 | Transaction style | Explicit context-managed transactions | Implicit/autobegin side effects |
 
@@ -115,6 +120,17 @@ Define one canonical model to migrate toward.
 
 Completion check: architecture diagram can explain where engine/session are created, used, and closed.
 
+### Step 1.5: Decide SQLModel Adoption Scope
+
+Decide where SQLModel should be introduced during modernization.
+
+- Prefer SQLModel when it reduces duplicated schema definitions between ORM entities and API data models.
+- Keep SQLAlchemy async engine/session lifecycle as the runtime foundation.
+- Use bounded adoption first (one module or feature area), then expand after validation.
+- If project is already heavily SQLAlchemy-only and stable, document rationale for staying SQLAlchemy-only.
+
+Completion check: plan includes an explicit SQLModel branch with target modules and non-goals.
+
 ### Step 2: Plan Engine Modernization
 
 Plan engine creation and pool behavior.
@@ -198,6 +214,7 @@ Create modernization quality gates.
 - Concurrency tests confirming one-session-per-task behavior.
 - Lifespan tests verifying cleanup calls and ordering.
 - Health/readiness tests including DB connectivity checks.
+- If SQLModel is adopted, model-validation tests cover SQLModel table models and API models at module boundaries.
 
 Completion check: all quality gates pass under the target async configuration.
 
@@ -222,6 +239,7 @@ A plan is complete only when it includes:
 - Explicit context-manager patterns for resource ownership.
 - AsyncExitStack composition strategy.
 - Transaction policy and exception behavior.
+- SQLModel adoption branch (use/adopt/defer) with rationale.
 - Concrete tests and rollout checkpoints.
 - A documented advisory backlog for non-critical implicit I/O improvements.
 
@@ -232,6 +250,7 @@ A plan is complete only when it includes:
 - Implicit commit/rollback behavior with unclear ownership.
 - Global mutable session state.
 - Lifespan cleanup that depends on implicit garbage collection.
+- Forcing SQLModel rewrites across the entire codebase in one phase without module-level rollout.
 
 ## Output Contract