# LinkML Slot File Editing Rules

## Rule 1: Preserve Original Descriptions
**NEVER alter the original English `description` field of LinkML slot files.**

When editing slot files:
- Keep the original `description` text exactly as provided
- Translations in `alt_descriptions` must accurately reflect the original English description
- Do not paraphrase, expand, or "improve" the original description
- If the description seems unclear, ask the user before making changes

## Rule 2: Translation Accuracy
All `alt_descriptions` translations must be faithful translations of the original English `description`, not creative interpretations or expansions.

## Rule 3: Description Field Purity
**The `description` field must contain ONLY the semantic definition of the slot.**

Comments, migration notes, usage examples, and other metadata MUST be placed in the appropriate YAML keys:

| Content Type | Correct Location | WRONG Location |
|--------------|------------------|----------------|
| Semantic definition | `description` | - |
| Migration notes | `comments` | `description` |
| Usage notes | `comments` | `description` |
| Examples | `examples` | `description` |
| Ontology alignment info | `comments` (or header) | `description` |
| Rule compliance notes | `comments` | `description` |
| Temporal semantics notes | `comments` | `description` |

### ❌ WRONG: Embedding comments in description

```yaml
slots:
  my_slot:
    description: |
      To possess or be associated with structured data.

      MIGRATED from `old_slot_name` per Rule 53.
      
      **USAGE**: Used for X, Y, Z.
```

### ✅ CORRECT: Separate description from comments

```yaml
slots:
  my_slot:
    description: |
      To possess or be associated with structured data.
    comments:
      - MIGRATED from old_slot_name per slot_fixes.yaml (Rule 53).
      - |
        **USAGE**: Used for X, Y, Z.
```

### Why This Matters

1. **Machine readability**: Tools parsing `description` expect only semantic content
2. **Translation accuracy**: Only the semantic definition should be translated to `alt_descriptions`
3. **Clean documentation**: Separation of concerns makes files easier to maintain
4. **Consistency**: All metadata follows the same pattern across all slot files