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" or "WELL_STRUCTURED_NO_MIGRATION_NEEDED" citing reasons like:

• "simple enum appropriate"
• "would add unnecessary indirection"
• "already has proper slot_uri"
• "string range is sufficient for this use case"
• "well-structured, no migration needed"
• "current implementation is adequate"

These judgments were INCORRECT.

Over 95% of entries in slot_fixes.yaml represent carefully curated migrations that MUST be executed.

The revisions were manually designed based on:

• Ontology analysis (CIDOC-CRM, RiC-O, PROV-O, Schema.org alignment)
• Semantic correctness
• Pattern consistency (Rule 39: RiC-O style naming)
• Type/Types class hierarchy design (Rule 0b)

Why Revisions MUST Be Executed

Principle	Explanation
Schema Consistency	Ontology achieves semantic power through consistent patterns, not local optimizations
LinkML Mapping Separation	slot_uri handles external ontology alignment; slot structure handles internal consistency
Single Responsibility Principle	Predicates should have single, focused purposes
Extensibility First	Structured classes enable future extension even if current use is simple
Curated Quality	Revisions were manually designed with ontology expertise - trust them

Invalid Reasons to Reject Migrations

Rejected Reason	Why It's Invalid
"Already has proper slot_uri"	slot_uri is for external mapping; internal structure is separate concern
"Simple string/enum is sufficient"	Consistency and extensibility trump local simplicity
"Would add unnecessary indirection"	Indirection enables reuse and future extension
"Creating a class would over-engineer"	Ontology design favors class-based modeling
"Well-structured, no migration needed"	If revision exists, migration IS needed
"Current implementation is adequate"	Adequacy is not the standard; consistency is
"WELL_STRUCTURED_NO_MIGRATION_NEEDED"	This note type is PROHIBITED

Valid Reasons to PAUSE Migrations (Not Reject)

These warrant discussion with the user, NOT unilateral rejection:

1. Semantic Conflict: Proposed slot_uri contradicts the semantic intent of the slot
2. Class Already Exists: The target class exists under a different name (propose merge)
3. Circular Dependency: Migration would create import cycles
4. Breaking External API: Change would break published external consumers

Even these reasons require escalation to the user - agents should NOT mark as "NO MIGRATION NEEDED".

The Key Insight

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

• External mapping (slot_uri, exact_mappings): How this slot relates to external ontologies
• Internal structure (range, class design): How this slot fits within the LinkML schema

A slot can have perfect external mappings AND still need structural migration for internal consistency.

Correct Agent Behavior

# When encountering a slot_fixes.yaml entry:

1. READ the revision specification completely
2. DO NOT evaluate whether migration is "necessary" - it IS necessary
3. CREATE the specified slots and classes
4. UPDATE the consuming class(es)
5. ARCHIVE the old slot
6. ADD processed section with status: true

# NEVER add notes like:
#   - "NO MIGRATION NEEDED"
#   - "WELL_STRUCTURED_NO_MIGRATION_NEEDED"
#   - "Current implementation is sufficient"
#   - "Would add unnecessary complexity"
#   - "Simple enum appropriate"

Handling Previous "NO MIGRATION NEEDED" Entries

Entries previously marked with notes like "WELL_STRUCTURED_NO_MIGRATION_NEEDED" should be:

1. Re-processed: The migration should be executed as specified in revision
2. Notes replaced: Replace the incorrect notes with actual migration documentation
3. Status verified: Ensure status: true reflects ACTUAL migration, not skipped migration

Example - WRONG Agent Behavior

# WRONG - Agent decided migration wasn't needed
- original_slot_id: https://nde.nl/ontology/hc/slot/cites_appendix
  revision:
  - label: is_or_was_listed_in
    type: slot
  - label: CITESAppendix
    type: class
  processed:
    status: true  # ← Marked complete but NOT actually migrated!
    notes: "WELL_STRUCTURED_NO_MIGRATION_NEEDED: Already has proper slot_uri 
            and string range is sufficient for CITES appendix values."

Example - CORRECT Agent Behavior

# CORRECT - Agent executed the migration as specified
- original_slot_id: https://nde.nl/ontology/hc/slot/cites_appendix
  revision:
  - label: is_or_was_listed_in
    type: slot
  - label: CITESAppendix
    type: class
  processed:
    status: true
    timestamp: '2026-01-19T00:00:00Z'
    session: session-2026-01-19-cites-appendix-migration
    notes: 'Migrated 2026-01-19 per Rule 53/56. Created is_or_was_listed_in.yaml.
      Created CITESAppendix.yaml class. Updated BiologicalObject.yaml.
      Archived: modules/slots/archive/cites_appendix_archived_20260119.yaml.'

Feedback Field

The feedback field in slot_fixes.yaml entries contains user corrections to agent mistakes. When feedback says things like:

• "I reject this!"
• "Conduct the migration"
• "Please conduct accordingly"
• "I altered the revision"

This means a previous agent incorrectly deferred the migration, and it MUST now be executed.

Schema Consistency Examples

Why "Simple URI is fine" is WRONG

# 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.

Why "Simple enum is appropriate" is WRONG

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

# CORRECT - Enables extension
has_or_had_mode:
  range: ThinkingMode
  # ThinkingMode can have: mode_type, confidence, effective_date, etc.

Rationale: Even if current use is simple, structured classes enable future extension without breaking changes.

Summary

Trust the revision. Execute the migration. Document the work.

The revision key in slot_fixes.yaml represents carefully curated ontology decisions. Agents are executors of these decisions, not evaluators. The only acceptable output is a completed migration with proper documentation.

Related Rules

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

Revision History

• 2026-01-19: Strengthened with explicit prohibition of "WELL_STRUCTURED_NO_MIGRATION_NEEDED" notes
• 2026-01-16: Created based on analysis of 51 feedback entries in slot_fixes.yaml