Nexus.Reader/.agent/skills/nexus-code-review/SKILL.md

name, description

name	description
nexus-code-review	Code Review Checklist and Standards for NexusReader SaaS

NexusReader Code Review Standards

When conducting or receiving a code review for NexusReader, ensure the implementation adheres to the following critical architectural and performance standards:

1. Architectural Boundaries (CQRS & Blazor Hybrid)

• Client vs. Server Execution: MediatR handlers that depend on server-side infrastructure (AppDbContext, IHubContext, secrets) MUST NOT be executed directly from client environments (WASM/MAUI).
• Dependency Leakage: Ensure NexusReader.Web.Client (WASM) does not reference NexusReader.Infrastructure if the infrastructure requires Microsoft.AspNetCore.App framework references.
• SignalR Bridges: Client-initiated state changes should be sent via SignalR SendAsync to a server Hub, which then dispatches the internal MediatR command.

2. Event Handling & Debouncing

• High-Frequency UI Events: UI actions like scrolling, resizing, or typing must be debounced.
• Trailing-Edge Debounce: Use a CancellationTokenSource and Task.Delay to ensure the last event in a rapid sequence is executed. Do not use simple time-window drops, as they result in lost final states.
• Async Void: Ensure UI event handlers do not use async void unless they are top-level framework event bindings, and even then, they must catch all exceptions.

3. SignalR & Real-Time Contexts

• Authentication Context: Do not rely on IHttpContextAccessor inside MediatR handlers triggered by SignalR Hubs. Use Context.UserIdentifier directly from the Hub and pass it as a command parameter.
• Connection State: Always check HubConnection.State == HubConnectionState.Connected before attempting to send messages from the client.
• Targeted Broadcasting: Use SignalR Groups (e.g., $"User_{userId}") to broadcast updates only to the devices owned by the relevant user.

4. Performance & Scalability

• Database Write Contention: High-frequency telemetry (like reading progress) should ideally be batched or cached in-memory before writing to SQL, unless real-time persistence is strictly required.
• Memory Leaks: Ensure all components and services that subscribe to events (e.g., OnProgressReceived, JS Observers) implement IDisposable or IAsyncDisposable and properly unsubscribe.

5. Standard Nexus Guidelines

• Result Pattern: Ensure all application logic returns Result or Result<T> via FluentResults. No exceptions for control flow.
• AI Prompts: Ensure changes to AI logic do not bypass the PromptRegistry or token estimation limits defined in AiSettings.

6. Code Review Comments

6.1 Posting Comments

• Code-Linked Comments: Every review comment must be anchored to a specific file and line range using the Gitea inline comment API (path + new_line_num/old_line_num). Free-floating general comments are only acceptable for summary notes that cannot be attributed to a single location.
• Severity Prefix: Prefix each comment with its severity so the author can prioritize: 🔴 Blocking, 🟡 Design/Architecture, or 🟢 Minor/Suggestion.
• Actionable Guidance: Each comment must include a concrete, actionable suggestion — not just a description of the problem. Where applicable, provide a corrected code snippet.

6.2 Resolving Comments (Author Responsibility)

• Reply Before Resolving: When a review comment has been addressed, the author must reply to the specific thread explaining how the issue was resolved (e.g., commit SHA, approach taken, or a reasoned rejection with justification). Do not close a thread without a reply.
• Link to Fix: If the resolution is a code change, include the commit SHA or a reference to the changed line in the reply (e.g., Fixed in abc1234 — moved the guard before CTS allocation).
• Close Only After Reply: Mark a thread as Resolved only after posting the reply. A thread with no reply must remain open, even if the underlying code has changed.
• Rejection Must Be Justified: If the author disagrees with a comment and chooses not to act on it, they must reply with a clear technical justification. The reviewer then decides whether to accept the reasoning and close the thread, or escalate it.