---
name: declaration-contract-design
description: Use when the user asks to design or refactor a declaration contract, such as a function signature, type shape, schema, or generic parameter list, and wants guidance on grouping, named vs positional elements, and stable ordering.
---

# Declaration Contract Design

Design or refactor declaration contracts using a Name plus Shape view so meaning stays explicit and the shape remains stable at use sites.

## Response Contract

- Deliverable: return the revised declaration contract.
- Chat output: no additional output beyond the deliverable.

## Skill Model

Definitions used to reason about declaration shape decisions.

### Grouping

Grouping is how a declaration organizes elements into conceptual blocks. A shape reflects the grouping decisions that were made.

### Addressing Modes

A declaration’s shape is addressed in one of two modes.

- **Named shape**
  Elements are addressed by name.

- **Positional shape**
  Elements are addressed by position.

## Standards

Each standard is defined once here and referenced elsewhere by its ID.

- **name.meaning — Name states meaning**
  Choose names that communicate domain meaning rather than implementation detail.

- **contract.core.explicit — Core meaning is explicit**
  Keep meaning-defining elements explicit in the declaration shape. Do not hide them inside unmodeled containers or convenience wrappers.

### Grouping

- **grouping.modeled_only — Grouping is a modeled concept**
  Introduce a group only when the group itself is a nameable concept with a stable semantic boundary.

- **grouping.no_catch_all — No catch-all groups**
  Do not use groups whose purpose is only to absorb leftovers or unrelated concerns.

### Positional shape

- **positional.role.anchor — Anchor role**
  Identifies the primary subject, such as a target, id, path, key.

- **positional.role.core — Core role**
  Required information that defines the primary semantic variation.

- **positional.role.policy — Policy role**
  Optional strategy and tuning that changes behavior without changing the subject.

- **positional.role.observability — Observability role**
  Diagnostics and tracing concerns.

- **positional.order.gradient — Order follows stability gradient**
  In positional shape, order elements by role: Anchor, Core, Policy, Observability.

- **positional.prefix.stable — Stable prefix discipline**
  Treat Anchor and Core as a stable prefix. After publication, do not reorder the stable prefix. Only append new positional elements at the tail.

### Callable declarations

- **callable.split — Split by role**
  When a callable uses both modes and the language supports named arguments, keep Anchor and Core in the positional segment and express Policy and Observability through named mechanisms.

- **callable.options.modeled — Options are modeled**
  If a callable introduces an options or config argument, it must be a modeled concept under `grouping.modeled_only` and must not become a catch-all under `grouping.no_catch_all`.

### Parameterized declarations

- **generics.semantic_order — Order by semantic priority**
  Order generic or type parameters by meaning: meaning-defining parameters first, constrained or defaulted parameters later, defaults at the end.

### Cross-cutting

- **conflicts.priority — Priority rule**
  When standards trade off, apply this priority order:

  1. `contract.core.explicit`
  2. `grouping.modeled_only`, `grouping.no_catch_all`
  3. `positional.order.gradient`, `positional.prefix.stable`
  4. Kind-specific standards for the declaration kind
  5. `name.meaning`

## Workflow

1. Identify the declaration kind and the meaning the contract must communicate. Apply `name.meaning` and `contract.core.explicit`.
2. Decide grouping boundaries if any. Apply `grouping.modeled_only` and `grouping.no_catch_all`.
3. Choose addressing mode for the shape or for shape segments.
4. If any segment is positional, assign roles and order by the stability gradient. Apply `positional.role.*`, `positional.order.gradient`, `positional.prefix.stable`.
5. Apply kind-specific standards.

   - Data-shape: no additional family beyond the base standards already applied.
   - Callable: apply `callable.*`.
   - Parameterized: apply `generics.*`.
6. Run acceptance checks.

## Acceptance Criteria

A revision is complete only if all checks pass.

- **Response**: Output satisfies the Response Contract.
- **Standards satisfied**:

  - Data-shape: `name.meaning`, `contract.core.explicit`, plus `grouping.*` when grouping is introduced, and `positional.*` when positional shape is used.
  - Callable: `name.meaning`, `contract.core.explicit`, `callable.*`, plus `grouping.*` when grouping is introduced, and `positional.*` when positional shape is used.
  - Parameterized: `contract.core.explicit`, `generics.*`, plus `positional.*` when positional shape is used.
  - Tradeoffs resolved by `conflicts.priority`.