554fe520ea
- 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.
144 lines
4.8 KiB
Markdown
144 lines
4.8 KiB
Markdown
# 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)
|
|
```yaml
|
|
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)
|
|
```yaml
|
|
feedback: I reject this! type_id should be migrated to has_or_had_identifier + Identifier
|
|
```
|
|
|
|
Or:
|
|
```yaml
|
|
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
|
|
```yaml
|
|
# 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
|
|
```yaml
|
|
feedback: Please conduct the migration accordingly.
|
|
notes: "NO MIGRATION NEEDED" # WRONG - feedback overrides notes
|
|
```
|
|
|
|
### WRONG: Treating all feedback as completed
|
|
```yaml
|
|
feedback: I altered the revision. Conduct this new migration.
|
|
processed:
|
|
status: true # WRONG if migration not actually done
|
|
```
|
|
|
|
## Correct Workflow
|
|
|
|
1. **Read feedback** - Understand user instruction
|
|
2. **Check revision** - This defines the target migration
|
|
3. **Execute migration** - Create/update slots and classes per revision
|
|
4. **Update processed.status** - Set to `true`
|
|
5. **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:
|
|
```yaml
|
|
- 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:
|
|
```yaml
|
|
- 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."
|
|
```
|
|
|
|
## See Also
|
|
|
|
- **Rule 53**: Full Slot Migration - slot_fixes.yaml is AUTHORITATIVE
|
|
- **Rule 57**: slot_fixes.yaml Revision Key is IMMUTABLE
|
|
- **Rule 39**: Slot Naming Convention (RiC-O Style)
|