kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/.opencode/rules/feedback-vs-revision-distinction.md
kempersc 4319f38c05 Add archived slots for audience size, audience type, and capacity metrics 
- Created new YAML files for audience size and audience type slots, defining their properties and annotations.
- Added archived capacity slots including cubic meters, linear meters, item count, and descriptions, with appropriate URIs and ranges.
- Introduced a template specificity slot for context-aware RAG filtering.
- Consolidated capacity-related slots into a unified structure, including has_or_had_capacity, capacity_type, and capacity_value, with detailed descriptions and examples.
2026-01-17 18:53:23 +01:00

4.8 KiB
Raw Permalink 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

  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:

- 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."

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)