Declaration Contract Design

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.