lantern

enhanced-look-formats-smart

🎯 Enhanced Look Formats with Smart Size Handling

Case Details

Case ID: task-b18d1a44-f7ae-4026-bf3c-f384b1f662c4 Status: parked Created: 2026-01-22T19:49:47.370Z Updated: 2026-01-22T19:49:47.370Z Priority: 3

Investigation Details

Case Type: analysis Urgency Level: routine Assigned Detective: claude

Notes

Feature Request

Add enhanced ______look formats to improve agent workflows and prevent context window bloat.

Requirements

1. Detailed Format

Return node content WITH fence metadata for complete structural view:

______look({ slug: "my-node", format: "detailed" })

Returns:

{
  "slug": "my-node",
  "content": "full markdown...",
  "fences": [
    {
      "index": 57,
      "type": "virtual:todo-list",
      "label": "my-tasks",
      "section": "Tasks",
      "metadata": {"item_count": 6}
    }
  ],
  "sections": [
    {"slug": "introduction", "level": 2},
    {"slug": "tasks", "level": 2}
  ],
  "stats": {
    "content_size": 4500,
    "fence_count": 3,
    "section_count": 5
  }
}

2. Index Format

Return structural overview WITHOUT full content:

______look({ slug: "my-node", format: "index" })

Returns:

{
  "slug": "my-node",
  "summary": "First 500 chars of content...",
  "sections": [
    {"slug": "introduction", "level": 2, "preview": "This guide explains..."},
    {"slug": "tasks", "level": 2, "preview": "Complete the following..."}
  ],
  "fences": [
    {"index": 57, "type": "virtual:todo-list", "label": "my-tasks", "section": "Tasks"}
  ],
  "stats": {
    "content_size": 45000,
    "fence_count": 12,
    "section_count": 15
  }
}

3. Smart Size-Based Auto-Selection

Automatic behavior:

  • Content < 10KB → return full content (default)
  • Content 10-50KB → return index format with warning
  • Content > 50KB → return index format, require explicit override
// Large node (45KB)
______look({ slug: "huge-node" })
// Auto-returns index format with message:
// "⚠️ Large node (45KB). Returning index. Use format='raw' to force full content."

// Force full content if needed
______look({ slug: "huge-node", format: "raw", force: true })

Use Cases

Agent discovers fence index without extra call

Before:

______look({ slug: "test" })  // See content
oculus_query_virtual_fences({ slug: "test" })  // Find fence index
____execute({ slug: "test", index: 57, ... })

After:

______look({ slug: "test", format: "detailed" })  // See content + fences
____execute({ slug: "test", index: 57, ... })

Agent browses large node without context bloat

Before:

______look({ slug: "cmd-poke" })  // Returns 50KB of content
// Context window overwhelmed

After:

______look({ slug: "cmd-poke" })  // Auto-returns index
// ⚠️ Large node (52KB). Showing index.
// See sections, fence inventory, can drill down to specific sections

Implementation Notes

Size Thresholds

  • Small: < 10KB (5,000 tokens) → full content
  • Medium: 10-50KB (5,000-25,000 tokens) → index + warning
  • Large: > 50KB (25,000+ tokens) → index only, require force flag

Override Mechanism

// Force full content despite size
______look({ slug: "huge", format: "raw", force: true })

// Explicit index even for small nodes
______look({ slug: "small", format: "index" })

Backward Compatibility

  • Default ______look({ slug: "node" }) maintains current behavior for small nodes
  • Only changes behavior for large nodes (improves experience)
  • All existing format options (raw, graph, yaml, markdown) still work

Related Work

  • cmd-look: Primary implementation target
  • cmd-peek: Consider similar index capability for large fence data
  • Performance optimization: Part of larger agent UX improvement

Success Criteria

  • Detailed format returns full content + fence metadata
  • Index format returns structure without overwhelming content
  • Size-based auto-selection prevents context bloat
  • Backward compatible with existing workflows
  • Clear messaging when auto-selection triggers

Investigation Timeline

2026-01-22T19:49:47.374Z - claude - case_created

Case opened from CLI

Consciousness Links

Context: Feature enhancement for look command with smart size handling

Auto-Detected Keywords

analysis

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

enhanced-look-formats-smart-1-detailed-format-fence-0

  • Status: 🔴 Unverified

enhanced-look-formats-smart-1-detailed-format-fence-1

  • Status: 🔴 Unverified

enhanced-look-formats-smart-2-index-format-fence-0

  • Status: 🔴 Unverified

enhanced-look-formats-smart-2-index-format-fence-1

  • Status: 🔴 Unverified

enhanced-look-formats-smart-3-smart-size-based-auto-selection-fence-0

  • Status: 🔴 Unverified

enhanced-look-formats-smart-agent-discovers-fence-index-without-extra-call-fence-0

  • Status: 🔴 Unverified

enhanced-look-formats-smart-agent-discovers-fence-index-without-extra-call-fence-1

  • Status: 🔴 Unverified

enhanced-look-formats-smart-agent-browses-large-node-without-context-bloat-fence-0

  • Status: 🔴 Unverified

enhanced-look-formats-smart-agent-browses-large-node-without-context-bloat-fence-1

  • Status: 🔴 Unverified

enhanced-look-formats-smart-override-mechanism-fence-0

  • Status: 🔴 Unverified