cosmos-design-struct

Cosmos SDK Struct Design Rules

When to use this skill

Use this skill when:

• Reviewing or validating struct design in the Cosmos SDK
• Generating new structs or modifying existing ones under sdk/cosmos/**
• Preparing a PR that introduces or changes public types
• Refactoring struct visibility or field access patterns
• Auditing the public surface area for breaking changes

Behavior

Follow these steps strictly:

Step 1 — Determine target path

• If the scope argument is specified and is not equal (case-insensitive) to all or *, set the target path to sdk/cosmos/<scope> (for example, if scope is azure_data_cosmos, use sdk/cosmos/azure_data_cosmos as the target path).
• Otherwise, set the target path to sdk/cosmos.
• Always include per-crate tests/ directories in the validation scope (e.g., sdk/cosmos/azure_data_cosmos/tests/).

Step 2 — Determine file scope

• If changed-only is true (the default), restrict scanning to .rs files that differ between the current local branch and main. Use git diff --name-only main -- <target path> (and include per-crate tests/ directories) to obtain the list. Only .rs files in the result set are scanned; all other files are skipped.
• If changed-only is false, scan all .rs files under the target path(s).
• In both modes, skip files in generated/ subdirectories — these are produced by external tools and must never be modified.

Step 3 — Scan struct declarations

• Find all struct declarations in the .rs files identified in Step 2.

Step 4 — Classify each struct

Classify every struct into exactly one of these categories:

1. Truly public — The struct is pub and all ancestor modules up to the crate root are also pub (the struct is reachable from outside the crate). These structs get the full set of rules: getter coverage for externally-readable fields, explicit field-visibility decisions based on invariants/validation needs, and a construction pattern that matches the required/optional field mix:

• It must expose Default when there are no logically required fields.
• It must expose new(required...) when the struct has both required and optional fields.
• For required-only structs, neither Default nor new(required...) is required by this skill.
• It must expose fluent with_* methods only for optional fields so callers can conveniently adjust a small subset of options.
• If a struct has exactly one field, do not force with_* methods.
• If a struct has only required fields (no optional overrides), do not force with_* methods.
• A separate builder type (builder()/build() + with_*) is optional, but if not used, the target struct itself must provide fluent with_* methods for optional fields when they exist.