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:

```yaml
# 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:

```yaml
# 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:

```yaml
# 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:

```yaml
# "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.

```yaml
# 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