broken-poke-operation

🎯 The Broken Poke Operation Semantics

Case Details

Case ID: task-056b686c-454e-46a6-a82d-45121e012081 Status: parked Created: 2026-01-22T19:37:37.676Z Updated: 2026-01-22T19:37:37.676Z Priority: 2

Investigation Details

Case Type: emergency-response Urgency Level: emergency Assigned Detective: Claude

Notes

The Mystery

The poke operation system has broken semantics and missing features:

content + append ignores the operation parameter and performs SET instead, causing data loss
insert_after:MARKER and insert_before:MARKER don't exist, preventing sibling insertion
Semantic confusion between child operations (append/prepend) and sibling operations (after/before)

Evidence Collected

Exhibit A: Data Loss Bug

Attempted to append to content:

_____poke({
  slug: "case-content-path-append-prepend-warning",
  path: "content",
  value: "\n\n## Investigation Tasks...",
  operation: "append",
  context: "Adding section"
})

Result: ENTIRE node content REPLACED instead of appended. Operation parameter completely ignored.

Exhibit B: Missing Operations

Documentation references insert_after:MARKER and insert_before:MARKER but they don't exist in the implementation.

Current operations:

set/replace (working)
append/prepend (work for sections, broken for content path)

Missing operations:

insert_after:MARKER
insert_before:MARKER

Exhibit C: Current Behavior

When appending to a section:

Content added WITHIN section (child relationship)
Headers automatically demoted to maintain hierarchy
## H2 appended to H2 section → becomes ### H3

No way to add sibling sections at the same level.

Correct Semantic Model

Document Root Synonyms

path: "content" = root of document
path: "h1-title-slug" = root of document
These should be identical operations

Child Operations (Demote Headers)

append = add child at end (demotes headers)
prepend = add child at start (demotes headers)

// Add child under section
_____poke({
  path: "parent-section",
  value: "## Child\n\nContent",
  operation: "append"  // Demotes to ### H3
})

// Append to document root
_____poke({
  path: "content",  // or h1-slug
  value: "## New Section\n\nContent",
  operation: "append"  // Stays ## H2, added at END
})

Sibling Operations (Preserve Level)

insert_after:MARKER = add sibling after (no demotion)
insert_before:MARKER = add sibling before (no demotion)

// Add sibling after section
_____poke({
  path: "some-section",
  value: "## Sibling\n\nContent",
  operation: "insert_after:some-section"  // Stays ## H2
})

Replacement Operations

set/replace = replace entire content
Warning + confirmation for content path

Required Fixes

1. Fix content + append Bug (CRITICAL)

Priority: P0 - Data loss bug

if path in ["content", h1_slug]:
    operation = params.get("operation", "set")
    
    if operation == "set":
        # Trigger warning
        trigger_confirmation()
        # Perform replacement
    elif operation == "append":
        # ACTUALLY APPEND to end of document
        append_to_root(value)
    elif operation == "prepend":
        # ACTUALLY PREPEND to start of document
        prepend_to_root(value)

2. Implement insert_after/insert_before

Priority: P1 - Missing functionality

if operation.startswith("insert_after:"):
    marker = operation.split(":", 1)[1]
    insert_sibling_after(marker, value)
elif operation.startswith("insert_before:"):
    marker = operation.split(":", 1)[1]
    insert_sibling_before(marker, value)

Test Cases

// Test 1: Append to content should append, not replace
_____poke({
  path: "content",
  value: "\n\n## New Section\n\nContent",
  operation: "append"
})
// Expected: Section added at END
// Actual: ENTIRE node replaced (BUG)

// Test 2: content and h1-slug should be equivalent
_____poke({ path: "content", operation: "append", value: "..." })
// Should equal:
_____poke({ path: "my-title", operation: "append", value: "..." })

// Test 3: insert_after for sibling
_____poke({
  path: "section-a",
  value: "\n\n## Section B\n\nContent",
  operation: "insert_after:section-a"
})
// Expected: ## Section B added after ## Section A (sibling)

// Test 4: append creates child with demotion
_____poke({
  path: "section-a",
  value: "\n\n## Sub Section\n\nContent",
  operation: "append"
})
// Expected: ### Sub Section under ## Section A (child)

Impact Assessment

Data Loss Risk: HIGH

Users following documentation experience node replacement
Confirmation prompt doesn't prevent data loss
Operation parameter silently ignored

User Confusion: HIGH

No way to add sibling sections
Unclear when headers get demoted
content path behaves differently than documented

Documentation Debt: HIGH

CLAUDE.md documents broken behavior
Proficiency test teaches non-functional pattern
Case nodes themselves were victims of this bug

Resources

Technical case documentation: ${case-content-path-append-prepend-warning}
User feedback: questionnaire-claude-20260122
Test implementation: oculus-proficiency-test
Command reference: cmd-poke

Investigation Timeline

2026-01-22T19:37:37.685Z - Claude - case_created

Case opened from CLI

Consciousness Links

Context: Critical bug in poke operation semantics causing data loss and missing sibling insertion operations

Auto-Detected Keywords

emergency

This case file is automatically updated. For investigation logs, see the corresponding log channel.

📋 Case To-Do List

This case has an integrated to-do list system that syncs with the Oculus knowledge graph. The to-do list uses the virtual:todo-list fence which auto-detects GitHub-style checkbox markdown.

How the To-Do System Works

Auto-Detection: Checkbox lists are automatically detected as virtual:todo-list fences
Alice Integration: Display in Alice dashboard using :::wonderland-todo-list slug="${current_case}"
ISA Operations: Use fence exec for add/check/update operations
Metadata Support: Add [assignee:name] [priority:level] tags to tasks

Case To-Do Operations

View state: oculus fence list ${slug} then oculus fence view ${slug} <fence-index>
Add task: oculus fence exec ${slug} <fence-index> add "New task"
Check task: oculus fence exec ${slug} <fence-index> check 0
Update task: oculus fence exec ${slug} <fence-index> update 0 "Updated content"
Reference: See virtual-fence-todo for full documentation

Current Case Tasks

🎯 Solve the case
📝 Document findings in investigation notes
🔗 Link relevant evidence and consciousness resources
✅ Update case status when complete

Next Steps

Add investigation notes and evidence tags as you progress. The to-do list will evolve with your investigation. Tasks can be managed via Oculus fence operations or edited directly in the node.

Provenance

Document

Status: 🔴 Unverified

Fences

broken-poke-operation-exhibit-a-data-loss-bug-fence-0

Status: 🔴 Unverified

broken-poke-operation-child-operations-demote-headers-fence-0

Status: 🔴 Unverified

broken-poke-operation-sibling-operations-preserve-level-fence-0

Status: 🔴 Unverified

broken-poke-operation-1-fix-content--append-bug-critical-fence-0

Status: 🔴 Unverified

broken-poke-operation-2-implement-insert_afterinsert_before-fence-0

Status: 🔴 Unverified

broken-poke-operation-test-cases-fence-0

Status: 🔴 Unverified