glam/.opencode/rules/class-description-quality-rule.md

# Class Description Quality Rule

## Rule: Write Dictionary-Style Definitions Without Repeating the Class Name

When writing class descriptions, follow these principles.

### 1. No Repetition of Class Name Components

**WRONG:**
```yaml
AcademicArchiveRecordSetType:
  description: >-
    A classification type for archival record sets created by academic
    institutions. This class represents the record set type...    
```

**CORRECT:**
```yaml
AcademicArchiveRecordSetType:
  description: >-
    Category for grouping documentary materials accumulated by tertiary
    educational institutions during their administrative, academic, and
    operational activities.    
```

The description should define the concept using synonyms and related terms, not repeat words from the class name.

### 2. MIGRATE Structured Data Before Removing from Descriptions

**CRITICAL**: When a description contains structured data (examples, typical contents, alignment notes, etc.), you MUST:

1. **First check** if the structured data already exists in proper LinkML fields
2. **If NOT present**: ADD it to the appropriate structured field
3. **ONLY THEN**: Remove it from the description

**Never simply delete structured content from descriptions without preserving it elsewhere.**

**MIGRATION CHECKLIST:**

| Content Type | Target Field | Example |
|--------------|--------------|---------|
| Example instances | `examples:` | `- value: {...} description: "..."` |
| Typical contents | `keywords:` or `comments:` | List of typical materials |
| Alignment explanations | `broad_mappings`, `related_mappings` | Ontology references |
| Usage notes | `comments:` | Operational guidance |
| Provenance notes | `comments:` or `annotations:` | Historical context |
| Privacy/legal notes | `comments:` | Access restrictions |
| Definition details | Keep in description | Core semantic definition |

**WRONG - Deleting without migration:**
```yaml
# BEFORE (has rich content)
description: |
  Records documenting student academic careers.
  
  **Typical Contents**:
  - Enrollment records
  - Academic transcripts
  - Graduation records
  
  Subject to privacy regulations (FERPA, GDPR).  

# AFTER (lost information!) - DON'T DO THIS
description: >-
  Records documenting student academic careers.  
```

**CORRECT - Migrate first, then clean:**
```yaml
# Step 1: Add to structured fields
description: >-
  Records documenting student academic careers.  
keywords:
  - enrollment records
  - academic transcripts
  - graduation records
comments:
  - Subject to privacy regulations (FERPA, GDPR, AVG)
  - Access restrictions typically apply for records less than 75 years old

# Step 2: Now description is clean but no information lost
```

### 3. No Structured Data or Meta-Discussion in Descriptions

After migration, descriptions should contain only the definition. Do not include:
- Alignment explanations (use `broad_mappings`, `close_mappings`, `exact_mappings`)
- Pattern explanations (use `see_also`, `comments`)
- Usage examples (use `examples:` annotation)
- Rationale for mappings (use `comments:` or `annotations:`)
- Typical contents lists (use `keywords:` or `comments:`)

**WRONG:**
```yaml
description: >-
  A type for X. 
  
  **RiC-O Alignment**: Maps to rico:RecordSetType because...
  
  **Pattern**: This is part of a dual-class pattern with Y.
  
  **Examples**: Administrative fonds, student records...  
```

**CORRECT:**
```yaml
description: >-
  Category for grouping documentary materials accumulated by tertiary
  educational institutions.  

broad_mappings:
  - rico:RecordSetType
see_also:
  - AcademicArchive
keywords:
  - administrative fonds
  - student records
examples:
  - value: {...}
    description: Administrative fonds containing governance records
```

### 4. Use Folded Block Scalar (`>-`) for Descriptions

Use `>-` (folded, strip) instead of `|` (literal) to ensure clean paragraph formatting in generated documentation.

**WRONG:**
```yaml
description: |
  A type for X.
  This spans multiple lines.  
```

**CORRECT:**
```yaml
description: >-
  A type for X. This will be formatted as a single clean paragraph
  in the generated documentation.  
```

### 5. Use LinkML `examples:` Annotation for Examples

Structure examples properly with `value:` and `description:` keys.

```yaml
examples:
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: University Administrative Records
  description: Administrative fonds containing governance records
```

### 6. Keywords vs Examples - Know the Difference

**CRITICAL**: Do not confuse `keywords:` with `examples:`. They serve different purposes:

| Field | Purpose | Content Type |
|-------|---------|--------------|
| `keywords:` | Search terms, topics, categories | List of strings (topics/materials) |
| `examples:` | Valid instance data demonstrations | Structured objects with `value` and `description` |

**Keywords** = Topics, material types, categories that describe what the class is about:
```yaml
keywords:
  - enrollment records      # type of material
  - academic transcripts    # type of material
  - graduation records      # type of material
```

**Examples** = Actual instances of the class with populated slots:
```yaml
examples:
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: Registrar Student Records
    has_note: Enrollment, transcripts, graduation records
  description: Student records series from the registrar's office
```

**WRONG - Using keywords as examples:**
```yaml
# DON'T: "enrollment records" is not an instance of AcademicStudentRecordSeries
examples:
- value: enrollment records
  description: Type of student record
```

**CORRECT - Keywords for topics, examples for instances:**
```yaml
keywords:
  - enrollment records
  - academic transcripts
  - graduation records
examples:
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: Historical Student Records
    has_note: Pre-1950 student records with fewer access restrictions
  description: Historical student records open for research access
```

### 7. Multiple Examples for Different Use Cases

Provide multiple examples to show different contexts or configurations:

```yaml
examples:
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: Recent Student Records
  description: Current records subject to privacy restrictions
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: Historical Student Records
  description: Records 75+ years old with fewer access restrictions
```

## Summary

| Element | Placement |
|---------|-----------|
| Definition | `description:` (concise, no repetition) |
| Ontology mappings | `exact_mappings`, `broad_mappings`, etc. |
| Related concepts | `see_also:` |
| Usage notes | `comments:` |
| Metadata | `annotations:` |
| Examples | `examples:` with `value` and `description` |
| Typical contents | `keywords:` or `comments:` |