Semantic Boundary Design
Role and Boundaries
Prevent semantic drift by assigning one owner to each meaning-defining decision. Many layers may observe, pass, or render the same data; only one should decide what it means for identity, lifecycle, permission, commands, routes, events, compatibility, or presentation.
Use this skill when one user/domain capability crosses representations and meaning rules are duplicated, inferred by callers, or preserved by adapters. Do not use it to discover current owners read-only, reshape local code after owners are settled, solve pure async responsiveness/freshness, or control change scope. Route those concerns respectively to source-owner audit, structure work, interactive-state flow, or the workflow that owns scope. When an excluded concern is primary, do not create an owner ledger or design its solution here; hand off only the observed behavior and constraints, without implementation mechanics.
Owner Ledger
- Name the capability in user or domain terms.
- Identify only relevant representation crossings: record/read model, UI draft or intent, route/query state, command input, API payload, result/event/patch, presentation model, or compatibility adapter.
- List decisions that could drift: identity/alias, lifecycle/status, permission/capability, command or navigation grammar, projection/presentation, compatibility, or cross-representation freshness/fallback/revision semantics.
- Assign exactly one owner per decision. Choose the smallest durable owner only when current evidence and authority both support the assignment. Otherwise record
decision needed -> missing evidence/authority; name a decision owner only when evidenced or explicitly provided.
- Define the caller boundary. Callers may pass, select, invoke, display, or render; they must not interpret, normalize, re-decide, or preserve policy they do not own.
Refactor only the scope justified by the current task. Semantic ownership does not authorize broader cleanup or implementation priority.
Placement Rules
- Record identities and field aliases belong to a record or contract owner.
- User intent belongs to its UI surface or command-input owner; final command payload belongs to the session or command owner.
- Business request parsing belongs to the application route, not a framework wrapper. Shared route/query grammar belongs to the navigation owner.
- Permissions and capabilities belong to the policy owner; labels and actions belong to the surface or view-model owner.
- Result envelopes, events, patches, and resync semantics belong to the application/realtime result owner.
- Cross-representation stale, pending, fallback, conflict, or revision acceptance belongs to the route, session, or screen that owns that semantic contract. Pure async behavior belongs outside this skill.
- An adapter translates shapes. It owns product policy only through an explicit, evidenced assignment.
Fallback chains outside their evidenced owner, duplicated status checks, caller-built final payloads, wrapper-owned business parsing, repeated freshness keys, and policy-preserving adapters are evidence that a decision has leaked from its owner—not automatic instructions to create a new layer.
Guards and Handoffs
Protect the stable owner boundary with the smallest useful contract, boundary, negative, type/schema, or user-visible regression test. Assert that the owner decides meaning once and callers cannot silently choose another meaning; do not freeze helper internals.
Report the capability, material crossings, owner ledger, caller boundary, observed leaks, required guards, and unresolved decisions only as needed for the task. Hand off source discovery, settled local structure, pure async interaction, and scope control when they become the primary problem, preserving the owner ledger so the next workflow does not reassign meaning without new evidence or authority.
1---2name: semantic-boundary-design3description: Use when cross-layer feature, migration, integration, port, refactor, review, bug fix, or design planning needs one owner for user/domain meaning across UI, route, client state, command, API, storage, realtime, adapter, or presentation layers. Trigger for identity aliases, lifecycle/status, permissions/capabilities, route/query grammar, command payloads, result/event projection, freshness/fallback/revision semantics across representations, compatibility translation, duplicated meaning rules, or multiple representations of the same user/domain meaning. Do not use for read-only owner discovery, local flow cleanup after owners are clear, pure async responsiveness/freshness work, or scope-control alone.4---56# Semantic Boundary Design78## Role and Boundaries910Prevent semantic drift by assigning one owner to each meaning-defining decision. Many layers may observe, pass, or render the same data; only one should decide what it means for identity, lifecycle, permission, commands, routes, events, compatibility, or presentation.1112Use this skill when one user/domain capability crosses representations and meaning rules are duplicated, inferred by callers, or preserved by adapters. Do not use it to discover current owners read-only, reshape local code after owners are settled, solve pure async responsiveness/freshness, or control change scope. Route those concerns respectively to source-owner audit, structure work, interactive-state flow, or the workflow that owns scope. When an excluded concern is primary, do not create an owner ledger or design its solution here; hand off only the observed behavior and constraints, without implementation mechanics.1314## Owner Ledger15161. Name the capability in user or domain terms.172. Identify only relevant representation crossings: record/read model, UI draft or intent, route/query state, command input, API payload, result/event/patch, presentation model, or compatibility adapter.183. List decisions that could drift: identity/alias, lifecycle/status, permission/capability, command or navigation grammar, projection/presentation, compatibility, or cross-representation freshness/fallback/revision semantics.194. Assign exactly one owner per decision. Choose the smallest durable owner only when current evidence and authority both support the assignment. Otherwise record `decision needed -> missing evidence/authority`; name a decision owner only when evidenced or explicitly provided.205. Define the caller boundary. Callers may pass, select, invoke, display, or render; they must not interpret, normalize, re-decide, or preserve policy they do not own.2122Refactor only the scope justified by the current task. Semantic ownership does not authorize broader cleanup or implementation priority.2324## Placement Rules2526- Record identities and field aliases belong to a record or contract owner.27- User intent belongs to its UI surface or command-input owner; final command payload belongs to the session or command owner.28- Business request parsing belongs to the application route, not a framework wrapper. Shared route/query grammar belongs to the navigation owner.29- Permissions and capabilities belong to the policy owner; labels and actions belong to the surface or view-model owner.30- Result envelopes, events, patches, and resync semantics belong to the application/realtime result owner.31- Cross-representation stale, pending, fallback, conflict, or revision acceptance belongs to the route, session, or screen that owns that semantic contract. Pure async behavior belongs outside this skill.32- An adapter translates shapes. It owns product policy only through an explicit, evidenced assignment.3334Fallback chains outside their evidenced owner, duplicated status checks, caller-built final payloads, wrapper-owned business parsing, repeated freshness keys, and policy-preserving adapters are evidence that a decision has leaked from its owner—not automatic instructions to create a new layer.3536## Guards and Handoffs3738Protect the stable owner boundary with the smallest useful contract, boundary, negative, type/schema, or user-visible regression test. Assert that the owner decides meaning once and callers cannot silently choose another meaning; do not freeze helper internals.3940Report the capability, material crossings, owner ledger, caller boundary, observed leaks, required guards, and unresolved decisions only as needed for the task. Hand off source discovery, settled local structure, pure async interaction, and scope control when they become the primary problem, preserving the owner ledger so the next workflow does not reassign meaning without new evidence or authority.
perhapsspy