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:

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

CORRECT:

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. No Structured Data or Meta-Discussion in Descriptions

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:)

WRONG:

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:

description: >-
  Category for grouping documentary materials accumulated by tertiary
  educational institutions.  

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

3. Use Folded Block Scalar (>-) for Descriptions

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

WRONG:

description: |
  A type for X.
  This spans multiple lines.  

CORRECT:

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

4. Use LinkML examples: Annotation for Examples

Structure examples properly with value: and description: keys.

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

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