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

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

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

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

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

### Why "Simple enum is appropriate" is WRONG

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