glam/.opencode/rules/semantic-consistency-over-simplicity.md

Rule 56: Semantic Consistency Over Simplicity - Always Execute slot_fixes.yaml Revisions

CRITICAL: When slot_fixes.yaml specifies a revision, agents MUST execute it. Perceived simplicity of the existing slot is NOT a valid reason to reject a migration.

The Core Problem

Previous agents marked migrations as "NO MIGRATION NEEDED" citing reasons like:

• "Simple enum appropriate"
• "Would add unnecessary indirection"
• "Already has proper slot_uri"
• "String range is sufficient"

These judgments were INCORRECT. The slot_fixes.yaml revisions exist for specific architectural reasons that transcend local optimization.

Why Revisions MUST Be Executed

1. Schema Consistency Principle

The ontology achieves semantic power through consistent patterns, not local optimizations:

# WRONG - Agent judgment: "Simple URI is fine"
thumbnail_url:
  range: uri
  slot_uri: schema:thumbnailUrl

# CORRECT - Consistent with all media references
has_or_had_thumbnail:
  range: Thumbnail  # Thumbnail class with has_or_had_url → URL

Rationale: All media references (images, thumbnails, videos, documents) should use the same structural pattern. Inconsistency creates cognitive load and maintenance burden.

2. LinkML Ontology Mapping Separation

The slot_uri property handles external ontology alignment. Slot structure handles internal consistency:

# slot_uri handles: schema:thumbnailUrl, foaf:thumbnail, etc.
# Slot structure handles: consistent pattern within our ontology
has_or_had_thumbnail:
  slot_uri: schema:thumbnailUrl
  exact_mappings:
    - foaf:thumbnail
  range: Thumbnail  # Internal consistency

Key Insight: Agents confused "has good external mapping" with "needs no migration". These are independent concerns.

3. Single Responsibility Principle (SRP)

Predicates should have single, focused purposes:

# WRONG - Overloaded predicate
applies_or_applied_to_call:
  description: "Used for both funding calls and application requirements"
  
# CORRECT - Single responsibility per predicate
applies_or_applied_to:
  description: "Expresses application relationship"
  
is_or_was_required_for:
  description: "Expresses requirement relationship"

4. Extensibility First

Even if current use is simple, structured classes enable future extension:

# "Simple enum is fine" - Agent judgment
thinking_mode:
  range: ThinkingModeEnum  # enabled, disabled, interleaved

# But this blocks: confidence scores, provenance, timestamps
# With class:
has_or_had_mode:
  range: ThinkingMode
  # ThinkingMode can have: mode_type, confidence, effective_date, etc.

Decision Rules for Agents

When slot_fixes.yaml Specifies a Revision

Agent Action	Status
Execute the revision exactly	CORRECT
Mark as "NO MIGRATION NEEDED"	WRONG
Substitute different slot/class	WRONG
Partially execute revision	WRONG

Invalid Reasons to Reject Migrations

These are NOT valid reasons to mark "NO MIGRATION NEEDED":

1. "Already has proper slot_uri" - slot_uri is for external mapping; internal structure is separate
2. "Simple string/enum is sufficient" - consistency and extensibility trump local simplicity
3. "Would add unnecessary indirection" - indirection enables reuse and future extension
4. "Range X is appropriate" - slot_fixes.yaml revision takes precedence
5. "Creating a class would over-engineer" - ontology design favors class-based modeling

Valid Reasons to Pause Migrations

These warrant discussion (not unilateral rejection):

1. Semantic conflict - Proposed slot_uri contradicts the semantic intent (e.g., ownership vs. physical movement)
2. Class already exists - Revision proposes class that already exists under different name
3. Circular dependency - Migration would create import cycle
4. Breaking change - Migration would break external consumers (document and discuss)

When in doubt: Execute the revision and document concerns for future discussion.

Feedback Patterns and Lessons

Pattern 1: "LinkML ontology mapping takes care of related semantics"

Meaning: Don't conflate slot_uri (external alignment) with slot structure (internal consistency). Both are needed.

# slot_uri handles external semantics
# Range and class structure handle internal consistency
has_or_had_code:
  slot_uri: schema:identifier  # External mapping
  range: Alpha2Code            # Internal structure

Pattern 2: "Follow the revision as is"

Meaning: Execute exactly what slot_fixes.yaml specifies. No substitutions.

Pattern 3: "Predicates should follow the Single Responsibility Principle (SRP)"

Meaning: Don't create multi-purpose predicates. Split into focused slots.

Pattern 4: "Provides consistency with other X in the ontology"

Meaning: Pattern consistency across the schema is more valuable than local optimization.

Implementation Checklist

Before marking any slot as "NO MIGRATION NEEDED", verify:

• Did you execute the revision from slot_fixes.yaml?
• Is your justification one of the "Invalid Reasons" listed above?
• Does your decision maintain consistency with similar slots?
• Have you considered extensibility implications?
• Is there a genuine semantic conflict (not just preference)?

Related Rules

• Rule 53: slot_fixes.yaml is AUTHORITATIVE - Full Slot Migration
• Rule 55: Broaden Generic Predicate Ranges Instead of Creating Bespoke Predicates
• Rule 39: RiC-O Temporal Naming Conventions
• Rule 38: Slot Centralization and Semantic URI Requirements

Revision History

• 2026-01-16: Created based on analysis of 51 feedback entries in slot_fixes.yaml