kempersc 554fe520ea Add comprehensive rules for LinkML schema management and ontology mapping

- Introduced Rule 42: No Ontology Prefixes in Slot Names to enforce clean naming conventions.
- Established Rule: No Rough Edits in Schema Files to ensure structural integrity during modifications.
- Implemented Rule: No Version Indicators in Names to maintain stable semantic naming.
- Created Rule: Ontology Detection vs Heuristics to emphasize the importance of verifying ontology definitions.
- Defined Rule 50: Ontology-to-LinkML Mapping Convention to standardize mapping practices.
- Added Rule: Polished Slot Storage Location to specify directory structure for polished slot files.
- Enforced Rule: Preserve Bespoke Slots Until Refactoring to prevent unintended migrations during slot updates.
- Instituted Rule 56: Semantic Consistency Over Simplicity to mandate execution of revisions in slot_fixes.yaml.
- Added new Genealogy Archives Registry Enrichment class with multilingual support and structured aliases.

2026-02-15 19:20:09 +01:00

4.8 KiB

Raw Blame History

Rule 58: Feedback vs Revision Distinction in slot_fixes.yaml

Summary

The feedback and revision fields in slot_fixes.yaml serve distinct purposes and MUST NOT be conflated or renamed.

Field Definitions

`revision` Field

Purpose: Defines WHAT the migration target is
Content: List of slots and classes to create
Authority: IMMUTABLE (per Rule 57)
Format: Structured YAML list with label, type, optional link_branch

`feedback` Field

Purpose: Contains user instructions on HOW the revision needs to be applied or corrected
Content: Can be string or structured format
Authority: User directives that override previous notes
Action Required: Agent must interpret and act upon feedback

Feedback Formats

Format 1: Structured (with `done` field)

feedback:
  - timestamp: '2026-01-17T00:01:57Z'
    user: Simon C. Kemper
    done: false  # Becomes true after agent processes
    comment: |
      The migration should use X instead of Y.      
    response: ""  # Agent fills this after completing

Format 2: String (direct instruction)

feedback: I reject this! type_id should be migrated to has_or_had_identifier + Identifier

Or:

feedback: I altered the revision based on this feedback. Conduct this new migration accordingly.

Interpretation Rules

Feedback Contains	Meaning	Action Required
"I reject this"	Previous `notes` were WRONG	Follow `revision` field instead
"I altered the revision"	User updated `revision`	Execute migration per NEW revision
"Conduct the migration"	Migration not yet done	Execute migration now
"Please conduct accordingly"	Migration pending	Execute migration now
"ADDRESSED" or `done: true`	Already processed	No action needed

Decision Tree

Is feedback field present?
├─ NO → Check `processed.status`
│       ├─ true → Migration complete
│       └─ false → Execute revision
│
└─ YES → What format?
         ├─ Structured with `done: true` → No action needed
         ├─ Structured with `done: false` → Process feedback, then set done: true
         └─ String format → Parse for keywords:
                           ├─ "reject" → Previous notes invalid, follow revision
                           ├─ "altered/adjusted revision" → Execute NEW revision
                           ├─ "conduct/please" → Migration pending, execute now
                           └─ "ADDRESSED" → Already done, no action

Anti-Patterns

WRONG: Renaming feedback to revision

# DO NOT DO THIS
# feedback contains instructions, not migration specs
revision:  # Was: feedback
  - I reject this! Use has_or_had_identifier

WRONG: Ignoring string feedback

feedback: Please conduct the migration accordingly.
notes: "NO MIGRATION NEEDED"  # WRONG - feedback overrides notes

WRONG: Treating all feedback as completed

feedback: I altered the revision. Conduct this new migration.
processed:
  status: true  # WRONG if migration not actually done

Correct Workflow

Read feedback - Understand user instruction
Check revision - This defines the target migration
Execute migration - Create/update slots and classes per revision
Update processed.status - Set to true
Add response - Document what was done
- For structured feedback: Set done: true and fill response
- For string feedback: Add new structured feedback entry confirming completion

Example: Processing String Feedback

Before:

- original_slot_id: https://nde.nl/ontology/hc/slot/type_id
  feedback: I reject this! type_id should be migrated to has_or_had_identifier + Identifier
  revision:
    - label: has_or_had_identifier
      type: slot
    - label: Identifier
      type: class
  processed:
    status: false
    notes: "Previously marked as no migration needed"

After processing:

- original_slot_id: https://nde.nl/ontology/hc/slot/type_id
  feedback:
    - timestamp: '2026-01-17T12:00:00Z'
      user: System
      done: true
      comment: "Original string feedback: I reject this! type_id should be migrated to has_or_had_identifier + Identifier"
      response: "Migration completed. type_id.yaml archived, consuming classes updated to use has_or_had_identifier slot with Identifier range."
  revision:
    - label: has_or_had_identifier
      type: slot
    - label: Identifier
      type: class
  processed:
    status: true
    notes: "Migration completed per user feedback rejecting previous notes."

4.8 KiB Raw Blame History

Rule 58: Feedback vs Revision Distinction in slot_fixes.yaml

Summary

Field Definitions

revision Field

feedback Field

Feedback Formats

Format 1: Structured (with done field)

Format 2: String (direct instruction)

Interpretation Rules

Decision Tree

Anti-Patterns

WRONG: Renaming feedback to revision

WRONG: Ignoring string feedback

WRONG: Treating all feedback as completed

Correct Workflow

Example: Processing String Feedback

See Also

4.8 KiB

Raw Blame History

`revision` Field

`feedback` Field

Format 1: Structured (with `done` field)