vsa-implementation-guard_skill

Overview

This skill enforces best practices and prevents common implementation mistakes for Blazor VSA C# code generation and modification. It automatically applies rules for Handlers, Validators, BoundaryServices, Entities, and Value Objects to keep code consistent and safe. The goal is to ensure transactional consistency, clear error propagation, and proper responsibility distribution.

How this skill works

When generating or editing C# code, the skill checks for forbidden patterns (for example SaveChangesAsync calls inside Handlers) and enforces required patterns (Result<T>, scoped services, Handler naming). It flags or rewrites code that violates rules and suggests correct alternatives, such as delegating business logic to Entities and avoiding DB access inside Validators. It also validates Value Object usage so EF Core-compatible comparisons are used.

When to use it

• During automated generation or programmatic modification of C# Handlers, Validators, BoundaryServices, Entities, or Value Objects.
• When adding or reviewing MediatR command/handler implementations to enforce transaction and naming conventions.
• When building or validating FluentValidation validators to ensure they contain only format/shape checks.
• When verifying DI registrations to guarantee scoped lifetimes for services using DbContext.
• When reviewing boundary or API-layer services to ensure business rules remain on Domain Entities.

Best practices

• Never call SaveChangesAsync() inside a Handler; rely on TransactionBehavior to persist changes.
• Keep business logic inside Entities (e.g., CanXxx() methods); BoundaryService should only delegate or perform existence checks.
• Return business errors using Result<T> instead of throwing exceptions for expected domain outcomes.
• Compare Value Objects by instance (e.g., Id == BoardId.From(guid)), not by accessing .Value in LINQ queries.
• Validators should perform only syntactic/format checks; do not access the database in validation rules.
• Register services as Scoped rather than Singleton to avoid captive dependency issues with DbContext.

Example use cases

• Auto-fix a generated Handler that incorrectly calls SaveChangesAsync by removing the call and returning Result<T>.
• Detect and replace business-if logic inside a BoundaryService with a call to an Entity.CanXxx() method.
• Validate a FluentValidation class to ensure no repository or DB calls are present and limit rules to format.
• Transform LINQ queries that compare ValueObject.Value into comparisons between ValueObject instances for EF compatibility.
• Scan DI registrations and flag any Singleton registrations that depend on scoped DbContext services.