---
name: add-query
description: Scaffold a new regular CQRS query with handler and DI registration. Use ONLY for single-entity lookups or non-queryable results. For list/collection queries, use /add-dynamic-query instead.
argument-hint: <description of the query in natural language>
---

# Add Query

Scaffold a new regular query based on: $ARGUMENTS

## Important: Is This the Right Skill?

**This skill is for the rare case.** Most queries should be dynamic queries (`/add-dynamic-query`).

Only use this for:
- Single entity by ID (e.g., `FetchOrderByIdQuery`)
- Non-entity results (e.g., `GetDashboardStatsQuery`, `CheckAvailabilityQuery`)
- Complex aggregation not expressible as IQueryable

If the user is asking for a list/collection query with filtering, sorting, or pagination → suggest `/add-dynamic-query` instead.

## Instructions

### 1. Determine the query name

Use descriptive, domain-oriented names:
- `FetchOrderByIdQuery` — fetching a single entity
- `GetSystemHealthQuery` — non-entity result
- `CheckInventoryAvailabilityQuery` — domain-specific check

### 2. Determine the feature folder

Place the file in: `Features/{DomainArea}/`

### 3. Create the file

Create `Features/{DomainArea}/{QueryName}Query.cs`:

```csharp
using Svrnty.CQRS.Abstractions;

namespace {ProjectNamespace}.Features.{DomainArea};

// 1. Query POCO
public record {QueryName}Query
{
    // Parameters — e.g., Id for lookups
}

// 2. Handler
public class {QueryName}QueryHandler : IQueryHandler<{QueryName}Query, {ResultType}>
{
    public Task<{ResultType}> HandleAsync({QueryName}Query query, CancellationToken cancellationToken = default)
    {
        throw new NotImplementedException();
    }
}
```

### 4. Register in DI

```csharp
builder.Services.AddQuery<{QueryName}Query, {ResultType}, {QueryName}QueryHandler>();

// With validator (if needed)
builder.Services.AddQuery<{QueryName}Query, {ResultType}, {QueryName}QueryHandler, {QueryName}QueryValidator>();
```

### 5. Proto message (if project uses gRPC)

```protobuf
// In the QueryService definition
rpc {QueryName} ({QueryName}QueryRequest) returns ({QueryName}QueryResponse);

message {QueryName}QueryRequest {
  // fields matching query properties
}

message {QueryName}QueryResponse {
  {ResultMessage} result = 1;
}
```

### 6. Summary

After creating everything, list what was created and where.