claude-code-arcane 1.1.1 → 1.3.0

package/skills/dotnet-architecture/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: dotnet-architecture
+description: "Arquitectura de backends .NET: Vertical Slice Architecture (features) y Clean Architecture (capas), con guía de cuándo usar cada una, estructura, patrones (MediatR/Result/outbox) y anti-patterns. Usar al diseñar o revisar la estructura de un proyecto ASP.NET Core."
+category: "backend"
+argument-hint: "[vertical-slice|clean|when-to-use]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# dotnet-architecture — VSA & Clean Architecture para .NET
+
+Dos enfoques production-ready para estructurar un backend ASP.NET Core. No son excluyentes: muchos proyectos
+usan Clean Architecture en el borde y slices verticales adentro. Esta skill ayuda a **elegir** y a aplicar
+cada uno correctamente.
+
+## MANDATORY WORKFLOW
+
+**No imponer arquitectura por moda. Elegir según complejidad del dominio y vida del proyecto.**
+
+### Step 0: Elegir enfoque (`when-to-use`)
+
+| Señal | Recomendación |
+|-------|---------------|
+| CRUD, prototipos, APIs chicas, dominio fino, equipo chico | **Vertical Slice** (o single project) |
+| Dominio complejo, reglas de negocio ricas, long-lived, varios equipos | **Clean Architecture** |
+| Necesitás aislar el dominio de frameworks/DB para test y reemplazo | **Clean Architecture** |
+| Querés velocidad y bajo overhead de indirección | **Vertical Slice** |
+
+> Evitá Clean Architecture para CRUD simple: los proyectos extra y la indirección cuestan más de lo que aportan
+> cuando la lógica de negocio es delgada. Empezá con Vertical Slice y migrá si el dominio crece.
+
+### Step 1: Aplicar la estructura
+
+- **Vertical Slice:** un folder por feature/use-case; cada slice tiene su request, handler, validator y endpoint juntos. Ver `references/project-structure.md`.
+- **Clean Architecture:** proyectos `Domain → Application → Infrastructure → Api`; las dependencias apuntan **hacia adentro**, nunca al revés. Ver `references/project-structure.md`.
+
+### Step 2: Patrones idiomáticos
+
+Leer `references/patterns.md`: MediatR/handlers por use-case, `IApplicationDbContext` (exponer EF Core sin repos
+genéricos), pipeline behaviors (validación/logging/transacción), Result pattern en vez de excepciones para flujo,
+y outbox pattern para consistencia entre DB y eventos.
+
+### Step 3: Revisar contra anti-patterns + checklist
+
+- `references/anti-patterns.md` — repos genéricos sobre EF Core, fat controllers, dependencias que apuntan hacia afuera, lógica de dominio en Infrastructure.
+- `references/checklist.md` — verificación de cierre antes de dar la estructura por buena.
+
+Antes de aplicar una reestructuración significativa, confirmar el approach con el usuario (Question → Decision → Approval). Si todo el checklist pasa → arquitectura **COMPLIANT**.
+
+## Resumen de enfoques
+
+| Aspecto | Vertical Slice | Clean Architecture |
+|---------|----------------|--------------------|
+| Eje de organización | Feature / use-case | Capa técnica |
+| Proyectos | 1 (+ tests) | 4 (Domain/App/Infra/Api) |
+| Acoplamiento entre features | Bajo (slices independientes) | Mediado por Application |
+| Overhead inicial | Bajo | Alto |
+| Mejor para | CRUD, features, velocidad | Dominios complejos, long-lived |
+| Riesgo | Duplicación entre slices | Sobre-ingeniería |
+
+## Próximos pasos
+
+Definida la arquitectura → `/dotnet-scaffold` para generar el proyecto, y `/dotnet-best-practices` para revisar el código contra las 40 reglas.
+
+---
+
+_Inspirado en [ardalis/CleanArchitecture](https://github.com/ardalis/CleanArchitecture), [nadirbad/VerticalSliceArchitecture](https://github.com/nadirbad/VerticalSliceArchitecture) y la guía de Vertical Slice de [Milan Jovanović](https://www.milanjovanovic.tech/blog/vertical-slice-architecture-dotnet). Adaptado al formato Arcane._

package/skills/dotnet-architecture/references/anti-patterns.md

@@ -0,0 +1,12 @@
+# Anti-Patterns
+
+- **`IRepository<T>` / `IUnitOfWork` genérico sobre EF Core** — el `DbContext` ya es repositorio (`DbSet<>`) y Unit of Work (`SaveChangesAsync`); envolverlo agrega indirección sin valor y te tapa LINQ/Include/proyecciones.
+- **Fat controllers / endpoints con lógica de negocio** — el endpoint solo traduce HTTP ↔ request y mapea el resultado; las reglas van en el handler/dominio, no en el controlador.
+- **Dependencias apuntando hacia afuera** — `Domain` referenciando `Infrastructure` o EF Core rompe la regla de dependencias: el dominio deja de ser testeable y reemplazable.
+- **Application anémica que solo reenvía a repos** — si el handler no hace más que `return repo.Get(id)`, la capa no aporta nada; movés lógica de negocio real al dominio/handler o eliminás la indirección.
+- **Filtrar entidades EF como respuestas de API** — exponer entidades de persistencia acopla el contrato HTTP al schema de la DB y arrastra lazy-loading/ciclos; devolvé DTOs en el borde.
+- **Forzar Clean Architecture en un CRUD simple** — cuatro proyectos y pipeline behaviors para listar y guardar registros es sobre-ingeniería; empezá con Vertical Slice o single project.
+- **Service locator estático / `BuildServiceProvider()` en `Program.cs`** — construir el provider a mano crea grafos duplicados y dependencias ocultas; registrá todo en el contenedor y dejá que resuelva por constructor.
+- **Un `Services/` y `Controllers/` gigantes** — organizar por tipo técnico dispersa cada feature en cinco carpetas; organizá por feature/slice para que un caso de uso viva junto.
+
+_Ref: https://www.milanjovanovic.tech/blog/vertical-slice-architecture-dotnet · https://github.com/ardalis/CleanArchitecture · https://learn.microsoft.com/en-us/ef/core/dbcontext-configuration/_

package/skills/dotnet-architecture/references/checklist.md

@@ -0,0 +1,19 @@
+# Checklist
+
+Verificá antes de dar la estructura por buena.
+
+- [ ] Las dependencias apuntan hacia adentro: `Api → Infrastructure → Application → Domain`
+- [ ] `Domain` no tiene `<ProjectReference>` ni paquetes de framework (sin EF, sin ASP.NET)
+- [ ] No hay `IRepository<T>` / `IUnitOfWork` genérico envolviendo EF Core
+- [ ] EF Core se expone vía `IApplicationDbContext` en Application, implementado en Infrastructure
+- [ ] En Vertical Slice, cada slice es autocontenido (request + handler + validator + endpoint)
+- [ ] Los slices no dependen entre sí (acoplamiento solo vía `Common`/`Infrastructure`)
+- [ ] DTOs en el borde: ninguna entidad EF se devuelve como respuesta de API
+- [ ] Cada handler tiene una sola responsabilidad (un caso de uso por archivo)
+- [ ] `Program.cs` es solo composition root (DI + pipeline + map endpoints), sin lógica de negocio
+- [ ] La validación corre en un pipeline behavior, no repetida en cada endpoint
+- [ ] Fallos esperados se modelan con `Result<T>`/`ErrorOr`, no con excepciones de flujo
+- [ ] Las migraciones EF Core están versionadas en git
+- [ ] El enfoque elegido (VSA vs Clean) corresponde a la complejidad real del dominio
+
+_Ref: https://github.com/ardalis/CleanArchitecture · https://github.com/nadirbad/VerticalSliceArchitecture · https://www.milanjovanovic.tech/blog/clean-architecture-folder-structure_

package/skills/dotnet-architecture/references/patterns.md

@@ -0,0 +1,118 @@
+# Patrones Idiomáticos (.NET 10 / ASP.NET Core)
+
+## Handler por caso de uso
+
+Un request (record) + un handler. Con MediatR o con un sender hand-rolled mínimo.
+
+```csharp
+public sealed record CreateOrder(Guid CustomerId, decimal Amount) : IRequest<Result<Guid>>;
+
+internal sealed class CreateOrderHandler(IApplicationDbContext db)
+    : IRequestHandler<CreateOrder, Result<Guid>>
+{
+    public async Task<Result<Guid>> Handle(CreateOrder cmd, CancellationToken ct)
+    {
+        var order = Order.Create(cmd.CustomerId, cmd.Amount);
+        db.Orders.Add(order);
+        await db.SaveChangesAsync(ct);
+        return order.Id;
+    }
+}
+```
+
+## IApplicationDbContext (EF Core detrás de una interfaz, sin repo genérico)
+
+Exponé el `DbContext` a través de una interfaz en `Application`; implementala en
+`Infrastructure`. El `DbContext` ya es Unit of Work + repositorio: no lo envuelvas.
+
+```csharp
+// Application/Common/IApplicationDbContext.cs
+public interface IApplicationDbContext
+{
+    DbSet<Order> Orders { get; }
+    DbSet<Customer> Customers { get; }
+    Task<int> SaveChangesAsync(CancellationToken ct = default);
+}
+
+// Infrastructure/Persistence/AppDbContext.cs
+public sealed class AppDbContext(DbContextOptions<AppDbContext> options)
+    : DbContext(options), IApplicationDbContext
+{
+    public DbSet<Order> Orders => Set<Order>();
+    public DbSet<Customer> Customers => Set<Customer>();
+}
+```
+
+## Pipeline behaviors (validación, logging, transacción)
+
+Cross-cutting concerns alrededor de cada handler, sin ensuciar la lógica.
+
+```csharp
+public sealed class ValidationBehavior<TReq, TRes>(IEnumerable<IValidator<TReq>> validators)
+    : IPipelineBehavior<TReq, TRes> where TReq : notnull
+{
+    public async Task<TRes> Handle(TReq req, RequestHandlerDelegate<TRes> next, CancellationToken ct)
+    {
+        foreach (var v in validators)
+        {
+            var result = await v.ValidateAsync(req, ct);
+            if (!result.IsValid) throw new ValidationException(result.Errors);
+        }
+        return await next();
+    }
+}
+```
+
+Un `TransactionBehavior` similar abre `BeginTransactionAsync` antes de `next()` y
+hace commit/rollback alrededor: el UnitOfWork vive acá, no en repos a mano.
+
+## Result pattern para fallos esperados
+
+No tires excepciones para flujo de negocio esperado (not found, validación, conflicto).
+Devolvé `Result<T>` (o `ErrorOr<T>`) y mapealo a HTTP en el endpoint.
+
+```csharp
+public readonly record struct Error(string Code, string Message);
+
+public async Task<Result<OrderDto>> Handle(GetOrder q, CancellationToken ct)
+{
+    var order = await db.Orders.FindAsync([q.Id], ct);
+    return order is null
+        ? new Error("Order.NotFound", "Order no existe")
+        : order.ToDto();
+}
+```
+
+## Outbox pattern (consistencia DB + eventos)
+
+Para publicar eventos de forma confiable: persistí el evento en una tabla `Outbox`
+**dentro de la misma transacción** que el cambio de datos. Un background worker
+(`BackgroundService`) lee la tabla y publica al broker; así nunca queda el estado
+guardado sin el evento ni el evento sin el estado.
+
+## TypedResults en minimal API endpoints
+
+El endpoint es delgado: traduce HTTP ↔ request y mapea el `Result` a status code.
+
+```csharp
+public static class OrderEndpoints
+{
+    public static void Map(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/orders").WithTags("Orders");
+
+        group.MapPost("/", async (CreateOrder cmd, ISender sender, CancellationToken ct) =>
+        {
+            var result = await sender.Send(cmd, ct);
+            return result.IsError
+                ? TypedResults.Problem(result.FirstError.Message)
+                : TypedResults.Created($"/orders/{result.Value}", result.Value);
+        });
+    }
+}
+```
+
+`TypedResults` da el tipo de respuesta exacto (útil para OpenAPI y tests) en vez del
+`Results` no tipado.
+
+_Ref: https://www.milanjovanovic.tech/blog/internal-vs-public-apis-in-clean-architecture · https://github.com/ardalis/CleanArchitecture · https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/responses_

package/skills/dotnet-architecture/references/project-structure.md

@@ -0,0 +1,78 @@
+# Estructura de Directorios
+
+Dos formas válidas de estructurar un backend .NET 10 / ASP.NET Core. Elegí según
+complejidad del dominio (ver `when-to-use` en la SKILL).
+
+## Vertical Slice Architecture (un proyecto)
+
+Cada feature es un folder autocontenido: request, handler, validator y endpoint
+viven juntos. Tocás un caso de uso → tocás un solo archivo/carpeta.
+
+```
+src/
+  Features/
+    Orders/
+      CreateOrder.cs          ← record Command + Handler + Validator juntos
+      GetOrders.cs            ← record Query + Handler (paginación/proyección)
+      OrderEndpoints.cs       ← MapGroup("/orders") + TypedResults
+    Customers/
+      RegisterCustomer.cs
+      CustomerEndpoints.cs
+  Common/
+    Behaviors/                ← ValidationBehavior, LoggingBehavior, TxBehavior
+    Result.cs                 ← Result<T> / Error compartido
+  Infrastructure/
+    AppDbContext.cs           ← EF Core DbContext (DbSet<> por entidad)
+    Migrations/               ← migraciones versionadas en git
+  Program.cs                  ← composition root: DI, pipeline, MapEndpoints
+appsettings.json
+```
+
+- Cada slice depende de `Common` e `Infrastructure`, no de otros slices.
+- Un slice nuevo = un archivo nuevo; borrarlo no rompe a los demás (bajo acoplamiento).
+- El `DbContext` es compartido; cada handler usa solo los `DbSet<>` que necesita.
+
+## Clean Architecture (cuatro proyectos)
+
+Separación por capa técnica. Las dependencias apuntan **hacia adentro**: el dominio
+no conoce a nadie; la infraestructura y la API dependen de las capas internas.
+
+```
+src/
+  MyApp.Domain/             ← Entidades, value objects, domain events, reglas
+    Entities/Order.cs       ← cero deps externas (ni EF, ni ASP.NET)
+    ValueObjects/Money.cs
+    Common/Entity.cs
+  MyApp.Application/        ← Casos de uso (handlers), DTOs, interfaces
+    Orders/CreateOrder.cs
+    Common/IApplicationDbContext.cs   ← expone DbSet<> + SaveChangesAsync
+    Common/Behaviors/
+  MyApp.Infrastructure/     ← EF Core, Identity, servicios externos
+    Persistence/AppDbContext.cs       ← : DbContext, IApplicationDbContext
+    Persistence/Migrations/
+    Services/EmailSender.cs
+    DependencyInjection.cs
+  MyApp.Api/                ← Endpoints, Program.cs, wiring de DI
+    Endpoints/OrderEndpoints.cs
+    Program.cs
+```
+
+### Dirección de las referencias (`.csproj`)
+
+```
+MyApp.Api            → referencia → MyApp.Infrastructure, MyApp.Application
+MyApp.Infrastructure → referencia → MyApp.Application
+MyApp.Application    → referencia → MyApp.Domain
+MyApp.Domain         → referencia → (NADA)
+```
+
+- `Domain.csproj` no tiene ningún `<ProjectReference>` ni paquete de framework.
+- `Application` define `IApplicationDbContext`; `Infrastructure` lo implementa.
+  Así la lógica de negocio depende de una abstracción, no de EF Core directamente.
+- La inversión de dependencias se logra en `Api/Program.cs`, que es el único lugar
+  que conoce a las cuatro capas y arma el grafo de DI.
+
+> Regla de oro: si una flecha de dependencia apunta hacia afuera del dominio, la
+> arquitectura está rota. El dominio es el centro estable.
+
+_Ref: https://github.com/ardalis/CleanArchitecture · https://github.com/nadirbad/VerticalSliceArchitecture · https://www.milanjovanovic.tech/blog/vertical-slice-architecture-dotnet_

package/skills/dotnet-best-practices/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: dotnet-best-practices
+description: "ASP.NET Core / C# production best practices: 40 reglas en 10 categorías (arquitectura, DI, errores, seguridad, performance, async, EF Core, testing, API, devops) priorizadas por impacto. Usar al escribir/revisar código .NET backend."
+category: "backend"
+argument-hint: "[architecture|di|errors|security|performance|async|database|testing|api|all]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# dotnet-best-practices — Guía priorizada por impacto
+
+40 reglas para aplicaciones ASP.NET Core (.NET 10) production-ready, organizadas en 10 categorías y priorizadas de **CRITICAL** a **LOW-MEDIUM**. Cada regla del catálogo (en `references/`) trae impacto, ejemplo incorrecto, ejemplo correcto y link a docs.
+
+## MANDATORY WORKFLOW
+
+**No aplicar las 40 reglas a ciegas. Diagnosticar primero, priorizar por impacto.**
+
+### Step 0: Determinar scope
+
+1. **¿Código nuevo o auditoría de existente?** Si es auditoría, leer primero el feature/proyecto objetivo.
+2. **¿Qué categoría aplica?** Mapear el área del problema (ver tabla) o usar `all` para review completa.
+3. **¿Hay síntomas concretos?** (deadlocks, N+1, 500 inconsistentes, leaks) → ir directo a la categoría relevante.
+
+### Step 1: Priorizar por impacto
+
+Aplicar en este orden — no bajar de nivel hasta resolver el anterior:
+
+| Prioridad | Categoría | Impacto | Reference |
+|-----------|-----------|---------|-----------|
+| 1 | Architecture | CRITICAL | `references/architecture.md` |
+| 2 | Dependency Injection | CRITICAL | `references/dependency-injection.md` |
+| 3 | Async & Concurrency | HIGH | `references/async.md` |
+| 4 | Error Handling | HIGH | `references/error-handling.md` |
+| 5 | Security | HIGH | `references/security.md` |
+| 6 | Performance | HIGH | `references/performance.md` |
+| 7 | Database & EF Core | MEDIUM-HIGH | `references/database.md` |
+| 8 | Testing | MEDIUM-HIGH | `references/testing.md` |
+| 9 | API Design | MEDIUM | `references/api-design.md` |
+| 10 | DevOps & Deployment | LOW-MEDIUM | `references/devops.md` |
+
+### Step 2: Aplicar + verificar
+
+Para cada regla relevante: leer el ejemplo correcto en el reference, aplicarlo, y verificar contra el checklist de cierre.
+
+### Step 3: Checklist de cierre
+
+- [ ] `<Nullable>enable</Nullable>` + warnings as errors; cero `#nullable disable`
+- [ ] Async end-to-end con `CancellationToken`; cero `.Result`/`.Wait()`/`.GetAwaiter().GetResult()`
+- [ ] DI por constructor con scope correcto; sin `BuildServiceProvider()` manual ni service locator
+- [ ] Errores vía `ProblemDetails` (RFC 7807); sin stack traces expuestos
+- [ ] Sin N+1 en EF Core (`Include`/projection); `AsNoTracking()` en lecturas
+- [ ] Migraciones versionadas; nunca `EnsureCreated()` en prod
+- [ ] AuthZ por policies declarativas; secrets en secret manager (no en `appsettings.json`)
+- [ ] Structured logging (Serilog JSON) + health checks
+- [ ] Tests con xUnit; integración contra Postgres real (Testcontainers), no mocks de DbContext
+
+Si todo el checklist pasa → código **COMPLIANT**. Antes de escribir cambios significativos, confirmar el approach con el usuario (Question → Decision → Approval).
+
+## Tabla de mapeo síntoma → categoría
+
+| Síntoma | Categoría |
+|---------|-----------|
+| Deadlocks / thread pool starvation / app cuelga | Async, Performance |
+| Lentitud en endpoints, muchas queries | Performance, Database |
+| `InvalidOperationException` de DI / scopes / captured dependency | DI, Architecture |
+| Errores 500 inconsistentes / leaks de stack traces | Error Handling |
+| Endpoints expuestos / brute force / data sensible en logs | Security |
+| Tests frágiles o que pegan a servicios/DB reales sin control | Testing |
+| Respuestas inconsistentes / over-fetching de entidades | API Design |
+
+## Próximos pasos
+
+Para estructurar el proyecto → `/dotnet-architecture`. Para iniciar un backend nuevo con estos defaults → `/dotnet-scaffold`.
+
+---
+
+_Adaptado de [github/awesome-copilot](https://github.com/github/awesome-copilot) (dotnet-best-practices), [dotnet/skills](https://github.com/dotnet/skills) y [Aaronontheweb/dotnet-skills](https://github.com/Aaronontheweb/dotnet-skills). Reorganizado al formato skill+references de Arcane._

package/skills/dotnet-best-practices/references/api-design.md

@@ -0,0 +1,75 @@
+# 9. API Design (MEDIUM)
+
+## 9.1 DTOs, Never Expose EF Entities — MEDIUM
+
+Serializar entidades de EF filtra columnas internas, arrastra relaciones y acopla el contrato HTTP al schema de la base. Usar DTOs/records dedicados.
+
+**Incorrecto:**
+```csharp
+app.MapGet("/users/{id}", async (int id, AppDbContext db) => await db.Users.FindAsync(id)); // expone la entidad
+```
+**Correcto:**
+```csharp
+public record UserDto(int Id, string Email);
+app.MapGet("/users/{id}", async (int id, AppDbContext db) =>
+    await db.Users.Where(u => u.Id == id).Select(u => new UserDto(u.Id, u.Email)).FirstOrDefaultAsync());
+```
+
+## 9.2 API Versioning — MEDIUM
+
+Versionar la API permite evolucionar el contrato sin romper clientes existentes. `Asp.Versioning` lo integra con minimal APIs y OpenAPI.
+
+**Correcto:**
+```csharp
+builder.Services.AddApiVersioning(o => o.DefaultApiVersion = new ApiVersion(1, 0));
+var v1 = app.NewVersionedApi().MapGroup("/api/v{version:apiVersion}").HasApiVersion(1.0);
+v1.MapGet("/orders", GetOrders);
+```
+
+## 9.3 Consistent Errors with ProblemDetails — MEDIUM
+
+`ProblemDetails` (RFC 9457) da un formato de error estándar y machine-readable en toda la API.
+
+**Correcto:**
+```csharp
+builder.Services.AddProblemDetails();
+app.UseExceptionHandler();
+// en un handler:
+return TypedResults.Problem(title: "Order not found", statusCode: StatusCodes.Status404NotFound);
+```
+
+## 9.4 Correct Status Codes via TypedResults — MEDIUM
+
+`TypedResults` devuelve el status code correcto de forma tipada y mejora los metadatos de OpenAPI.
+
+**Correcto:**
+```csharp
+app.MapPost("/orders", async (CreateOrder cmd, IOrderService svc) =>
+{
+    var order = await svc.CreateAsync(cmd);
+    return TypedResults.Created($"/orders/{order.Id}", order); // 201 + Location
+});
+```
+
+## 9.5 Pagination & Idempotency for Writes — MEDIUM
+
+Paginar colecciones evita respuestas ilimitadas; una Idempotency-Key hace que un POST repetido (reintento de red) no duplique el recurso.
+
+**Correcto:**
+```csharp
+app.MapGet("/orders", (int page = 1, int pageSize = 20) => /* Skip/Take con límites */ );
+app.MapPost("/payments", ([FromHeader(Name = "Idempotency-Key")] string key, Payment p) =>
+    /* deduplicar por key antes de procesar */ );
+```
+
+## 9.6 Built-in OpenAPI — LOW
+
+`Microsoft.AspNetCore.OpenApi` genera el documento OpenAPI sin dependencias externas.
+
+**Correcto:**
+```csharp
+builder.Services.AddOpenApi();
+app.MapOpenApi(); // /openapi/v1.json
+```
+
+_Ref: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/apiversioning · https://learn.microsoft.com/en-us/aspnet/core/web-api/handle-errors · https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview · https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/responses_

package/skills/dotnet-best-practices/references/architecture.md

@@ -0,0 +1,62 @@
+# 1. Architecture (CRITICAL)
+
+## 1.1 Organize by Feature, Not Technical Layers — CRITICAL
+
+Carpetas por feature (vertical slice) → cohesión alta y cambios localizados; las carpetas por capa técnica dispersan un cambio en 5 sitios.
+
+**Incorrecto** — carpetas técnicas globales:
+```csharp
+// Controllers/, Services/, Repositories/, Dtos/ ... un cambio toca 4 carpetas
+```
+**Correcto** — un slice por feature:
+```csharp
+// Features/Orders/{ CreateOrder.cs, GetOrder.cs, OrdersEndpoints.cs, OrderDto.cs }
+// Features/Users/{ RegisterUser.cs, UsersEndpoints.cs, UserDto.cs }
+```
+
+## 1.2 Thin Endpoints — CRITICAL
+
+El endpoint parsea, delega y forma la respuesta. Sin lógica de negocio: así es testeable y reutilizable desde otros transportes.
+
+**Incorrecto:**
+```csharp
+app.MapPost("/orders", async (CreateOrderDto dto, AppDbContext db) =>
+{
+    if (dto.Items.Count == 0) return Results.BadRequest();   // negocio en el endpoint
+    var total = dto.Items.Sum(i => i.Price * i.Qty);          // negocio en el endpoint
+    db.Orders.Add(new Order { Total = total });
+    await db.SaveChangesAsync();
+    return Results.Ok();
+});
+```
+**Correcto:**
+```csharp
+app.MapPost("/orders", async (CreateOrderRequest req, CreateOrderHandler handler, CancellationToken ct) =>
+{
+    var result = await handler.HandleAsync(req, ct);
+    return result.IsSuccess ? Results.Created($"/orders/{result.Value.Id}", result.Value) : result.ToProblem();
+});
+```
+
+## 1.3 Dependencies Point Inward / Slices Independent — HIGH
+
+El dominio no conoce infraestructura (Clean Architecture): el handler depende de una abstracción `IOrderRepository`, no de `AppDbContext`. Entre slices, sin acoplamiento directo; coordinar vía eventos de dominio o un mediador.
+
+## 1.4 Single Responsibility per Handler — HIGH
+
+Un handler resuelve un caso de uso. `CreateOrderHandler` no envía emails ni cobra: emite un evento y otro handler reacciona. Mejora testabilidad y limita el blast radius de cada cambio.
+
+## 1.5 Program.cs as Composition Root Only — MEDIUM-HIGH
+
+`Program.cs` solo registra servicios y arma el pipeline; nada de lógica de negocio. Mover el wiring a extensiones (`builder.Services.AddOrdersFeature()`) mantiene el root legible.
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddOrdersFeature().AddAuthFeature();
+var app = builder.Build();
+app.UseExceptionHandler().UseAuthorization();
+app.MapOrdersEndpoints();
+app.Run();
+```
+
+_Ref: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures · https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/min-api-filters_

package/skills/dotnet-best-practices/references/async.md

@@ -0,0 +1,62 @@
+# 3. Async & Concurrency (HIGH)
+
+## 3.1 Async All the Way — CRITICAL
+
+`.Result`, `.Wait()` y `.GetAwaiter().GetResult()` bloquean el hilo: deadlocks y thread-pool starvation bajo carga. Propagar `async`/`await` de punta a punta.
+
+**Incorrecto:**
+```csharp
+public Order Get(int id) => repo.GetAsync(id).Result; // bloquea el thread-pool
+```
+**Correcto:**
+```csharp
+public async Task<Order> GetAsync(int id, CancellationToken ct) => await repo.GetAsync(id, ct);
+```
+
+## 3.2 Accept and Propagate CancellationToken — HIGH
+
+El token aborta el trabajo cuando el cliente corta la conexión, liberando hilos y conexiones de DB. Pasarlo a cada llamada async, hasta EF Core y `HttpClient`.
+
+**Correcto:**
+```csharp
+app.MapGet("/orders/{id:int}", async (int id, AppDbContext db, CancellationToken ct) =>
+    await db.Orders.FirstOrDefaultAsync(o => o.Id == id, ct) is { } o ? Results.Ok(o) : Results.NotFound());
+```
+
+## 3.3 No async void — HIGH
+
+`async void` no se puede esperar y sus excepciones tumban el proceso. Usar `async Task`. La única excepción son los event handlers de UI/eventos.
+
+**Incorrecto:**
+```csharp
+public async void Process() => await DoWorkAsync(); // excepción => crash no observable
+```
+**Correcto:**
+```csharp
+public async Task ProcessAsync(CancellationToken ct) => await DoWorkAsync(ct);
+```
+
+## 3.4 ConfigureAwait(false) in Libraries — MEDIUM-HIGH
+
+En código de librería reutilizable, `ConfigureAwait(false)` evita volver al contexto capturado y previene deadlocks en hosts con `SynchronizationContext`. En apps ASP.NET Core (sin contexto) no hace falta.
+
+```csharp
+var data = await httpClient.GetStringAsync(url, ct).ConfigureAwait(false);
+```
+
+## 3.5 Task.WhenAll for Parallel Independent Work — MEDIUM-HIGH
+
+Operaciones independientes en paralelo en vez de secuencial. No compartir un `DbContext` entre tasks concurrentes (no es thread-safe): usar un scope/contexto por task.
+
+```csharp
+var (user, prefs) = (await Task.WhenAll(GetUserAsync(id, ct), GetPrefsAsync(id, ct))) switch
+{
+    var r => (r[0], r[1])
+};
+```
+
+## 3.6 No Fire-and-Forget Without Error Handling — HIGH
+
+Un `Task` descartado traga excepciones y puede morir al reciclar el proceso. Para trabajo en background usar un `BackgroundService` / cola, con logging del error.
+
+_Ref: https://learn.microsoft.com/en-us/dotnet/csharp/asynchronous-programming/async-scenarios · https://learn.microsoft.com/en-us/dotnet/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern_

package/skills/dotnet-best-practices/references/database.md

@@ -0,0 +1,69 @@
+# 7. Database & EF Core (MEDIUM-HIGH)
+
+## 7.1 Avoid N+1 with Include or Projection — HIGH
+
+Acceder a relaciones en un loop dispara una query por fila. Usar `Include` o proyectar a un DTO con `Select` resuelve todo en una sola query.
+
+**Incorrecto:**
+```csharp
+var orders = await db.Orders.ToListAsync();
+foreach (var o in orders) o.Customer = await db.Customers.FindAsync(o.CustomerId); // N+1
+```
+**Correcto:**
+```csharp
+var orders = await db.Orders
+    .Select(o => new OrderDto(o.Id, o.Customer.Name, o.Total))
+    .ToListAsync();
+```
+
+## 7.2 AsNoTracking for Read-Only Queries — HIGH
+
+El change tracker añade overhead innecesario en lecturas. `AsNoTracking()` evita las snapshots y reduce allocations.
+
+**Correcto:**
+```csharp
+var products = await db.Products.AsNoTracking().Where(p => p.Active).ToListAsync();
+```
+
+## 7.3 DbContext is the Unit of Work — MEDIUM-HIGH
+
+`DbContext` ya implementa Unit of Work + Repository. Envolverlo en un repositorio genérico oculta `Include`, proyecciones y `SaveChanges`, añadiendo abstracción sin valor.
+
+**Incorrecto:**
+```csharp
+public class GenericRepository<T> { Task<T> GetById(int id); /* envuelve DbSet sin necesidad */ }
+```
+**Correcto:**
+```csharp
+// Inyectar AppDbContext (o un servicio de dominio que lo use) directamente
+public sealed class OrderService(AppDbContext db) { /* usa db.Orders, db.SaveChangesAsync */ }
+```
+
+## 7.4 Versioned Migrations, Never EnsureCreated in Prod — MEDIUM-HIGH
+
+`EnsureCreated()` no usa migraciones y no es upgradeable: hay que migrar el schema versionado con la CLI de EF.
+
+**Incorrecto:**
+```csharp
+await db.Database.EnsureCreatedAsync(); // no migrable, pierde historial de schema
+```
+**Correcto:**
+```bash
+dotnet ef migrations add AddOrderIndex
+dotnet ef database update    # en deploy: db.Database.MigrateAsync()
+```
+
+## 7.5 Connection Resiliency & Split Queries — MEDIUM
+
+Habilitar reintentos ante fallos transitorios y `AsSplitQuery()` para `Include` grandes evita la explosión cartesiana de un único JOIN.
+
+**Correcto:**
+```csharp
+builder.Services.AddDbContext<AppDbContext>(o =>
+    o.UseNpgsql(conn, npgsql => npgsql.EnableRetryOnFailure()));
+
+var blogs = await db.Blogs.Include(b => b.Posts).Include(b => b.Tags)
+    .AsSplitQuery().ToListAsync();
+```
+
+_Ref: https://learn.microsoft.com/en-us/ef/core/querying/related-data/eager-loading · https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations · https://learn.microsoft.com/en-us/ef/core/miscellaneous/connection-resiliency_