query-derivation

name	query-derivation
description	Rules for deriving the query part of a domain diagram (Query<X>Repository, <X>Info, nested *Info, <X>Filtering, Brief<X>Info, <X>ListResult) from the command part.
when_to_use	Use when generating or regenerating the query block of a Mermaid domain diagram from its command block — consulted by the derive-query-part skill and the query-part-deriver agent.
user-invocable	false

Query Part Derivation

Purpose

A domain diagram in this project has a command part (the aggregate root, its Command<X>Repository, child entities / value objects, domain events, and <<TypedDict>> data structures) and a query part (the read-side classes). The query part is almost entirely a mechanical projection of the command part.

This skill is the single source of truth for that projection. It is consulted by:

• model-diagrams:derive-query-part — the orchestrator skill that interviews the user and delegates the write.
• model-diagrams:query-part-deriver — the agent that parses the command part and writes the query classes in place.

Both must derive identical output from identical input; divergence between them is a bug in whichever one drifted from this skill.

Command-part inputs

From the classDiagram block, identify:

• <X> — the single <<Aggregate Root>> class. Its private fields (-name) and its computed properties (+status) are the source of the read model.
• Command<X>Repository — the <<Repository>> whose name starts with Command. Its lookup methods seed the query repository.
• Child classes — every <<Entity>> / <<Value Object>> reachable from <X> through composition (*--) or aggregation (o--).
• Command-side <<TypedDict>> — *Data types and shared types (e.g. Globals, ParsingError). These are reuse candidates (see Type reuse rule).

Domain events, domain services, and Command<X>Repository itself are not projected — the query part ignores them.

<x> below is the aggregate name in snake_case; <X> is the class name.

Query-part outputs

Emit these six class kinds, in this order, at the tail of the classDiagram block — after the last command class, before the closing ```.

1. Query<X>Repository <<Repository>>

• find_<x>(<x>_id: str) <X>Info | None — always emitted; the projection of Command<X>Repository.<x>_of_id.
• For each alternate lookup on the command repository — any method returning the aggregate <X> that is not <x>_of_id (e.g. template_of_source_id, project_with_details) — a find_<x>_by_<thing>(<same params>) <X>Info | None. <thing> is the distinguishing noun (template_of_source_id → find_template_by_source; project_with_details → find_project_by_details). Whether each alternate lookup is projected is a feedback point (see below).
• find_<x>s(filtering: <X>Filtering | None, pagination: Pagination | None) <X>ListResult — always emitted.
• has_* methods, save, and delete are never projected.

Pagination is an external shared type — reference it, never declare it.

2. <X>Info <<TypedDict>>

The full read model. One field per aggregate-root field, all public (+), applying the Field flattening rules. Computed properties (+status, +errors) are included as plain fields. Field omission is a feedback point.

3. Nested <Child>Info <<TypedDict>>

For every child collection surfaced in <X>Info (or recursively in another <Child>Info), emit a <Child>Info <<TypedDict>> derived from the child class by the same rules — unless the type reuse rule applies.

4. <X>Filtering <<TypedDict>>

Optional scalar filter fields, each typed T | None. The proposed default set is every filterable scalar on the aggregate — typically name, code, enabled, status, and aggregate-specific scalars (evo_version, project_type, …). id, created_at, and updated_at are excluded. The final set is a feedback point.

5. Brief<X>Info <<TypedDict>>

The list-row projection: every scalar field of <X>Info, dropping every list[...] field and every nested-<<TypedDict>> field. Keeps id, code, name, enabled / status, identity scalars (source_id, evo_version), created_at, updated_at.

6. <X>ListResult <<TypedDict>>

Exactly two fields:

• <x>s: list[Brief<X>Info] — the field name is the snake_case plural of the aggregate. When the plain plural reads awkwardly, a _list suffix is used (e.g. conversion_reqs_list).
• total: int.

Field flattening rules

Applied when projecting any class (<X> or a child) into a *Info <<TypedDict>>:

• Scalar field (str, int, bool, datetime, str | None, …) — copied verbatim, visibility changed to +.
• Single value-object field (details: Details) — inlined: the VO's own scalar fields are spliced in, the VO field itself disappears. DomainType with details: Details { name, description } → DomainTypeInfo carries name and description, not details.
• Collection field — a Collection Value Object (categories: Categories) or a direct list (lookups: list[Lookup]) — flattened to <field>: list[<Child>Info].
• Computed property (+status: str) — copied as a plain field.

Type reuse rule

When a field's projected shape exactly matches an existing command-side <<TypedDict>>, reference that type instead of minting a parallel *Info:

• A whole child whose read shape equals an existing TypedDict → reuse it (Globals is referenced directly by TemplateInfo; ParsingError by ConversionReqsInfo).
• A single field whose element type matches a command-side TypedDict → reference it inside the otherwise-new *Info (LookupInfo is minted because Lookup carries an id the command LookupData lacks, but its arguments / response fields still reuse LookupArgumentData / EntryItemData).

Mint a new <Child>Info only when the shape genuinely diverges. The rule is applied per field, recursively.

Relationship arrows

After the query classes, emit:

Query<X>Repository --> <X>Info : returns
Query<X>Repository --> <X>ListResult : returns
Query<X>Repository --> <X>Filtering : takes as argument

For each nested collection field in an *Info:

• Minted <Child>Info → composition: <Parent>Info *-- "<mult>" <Child>Info.
• Reused command-side TypedDict → lollipop: <Parent>Info --() "<mult>" <Type>.

<mult> is the multiplicity of the collection in the command part — for a flattened Collection VO it is the Collection-VO-to-element multiplicity (Categories *-- "0..n" Category → TemplateInfo *-- "0..n" CategoryInfo).

Always emit <X>ListResult *-- "0..n" Brief<X>Info.

Regeneration (in-place replace)

The query part may already exist (a re-run after the command part changed). Recognize the existing query classes by name — Query<X>Repository, <X>Info, every nested <Child>Info, <X>Filtering, Brief<X>Info, <X>ListResult — and their arrows. Remove all of them, then re-emit the freshly derived query part at the tail of the classDiagram block. Command classes and the ## Invariants prose are never touched.

Feedback points

Three derivation decisions are not mechanical and are settled by interviewing the user. Defaults below apply when no feedback is given.

Decision	Default
Which alternate command-repo lookups become find_<x>_by_*	all of them
Which aggregate fields are omitted from <X>Info	none — full mirror
Which scalars <X>Filtering exposes	the proposed default set above