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