lantern

oculus-terminal-velocity-summary

Oculus Terminal Velocity - Executive Summary

Detective Case: task-bc17ac6a-e1cf-4d32-8fd9-bb280a11fa3f

The Problem

The oculus CLI is too slow to use effectively:

  • 45+ commands when should be ~20
  • Can't quickly execute fences (need to find index manually)
  • Can't quickly access headers or sections
  • No format control (stuck with whatever output format we get)
  • Modes not exposed or clear
  • Tags/metadata as separate commands instead of peek/poke

Key Insights

1. Look vs Goto Are Different

goto: Changes server-side position state (POST) look: Read-only view (GET)

They're NOT the same thing with navigation - goto has side effects, look doesn't.

2. The Fence ID Problem

Current (slow):

oculus fence list daily-tasks
# manually count to find TODO list at index 3
oculus fence exec daily-tasks 3 add --content "Task"

Needed (fast):

oculus execute daily-tasks:TODO add --content "Task" --format json

3. Missing Quick Data Access

Can't:

  • List headers quickly
  • Peek specific header content
  • Get data in preferred format (JSON vs markdown)
  • Execute by fence name/ID

4. Mode vs Format Confusion

Mode = Processing level (raw/interpolated/rendered/executed) Format = Output serialization (json/yaml/markdown/raw/text)

Both needed, both should be exposed on all commands.

The Solution: Three Phases

Phase 1: Fence ID System ⚡ (HIGH PRIORITY)

Enable fast fence execution:

# By name (best)
oculus execute daily-tasks:TODO add --content "Task" --format json

# By global ID  
oculus execute fence-abc123 add --content "Task" --format json

# Current (keep for compatibility)
oculus execute daily-tasks:3 add --content "Task"

What to build:

  • Fence registry with global UUIDs
  • Fence name support in metadata
  • Address parser (slug:name, slug:index, fence-id)
  • New endpoint: POST /api/oculus/fence/{fence_address}/execute

Phase 2: Header Operations ⚡ (HIGH PRIORITY)

Enable quick header access:

# List all headers
oculus peek daily-tasks headers

# Get prose under header
oculus peek daily-tasks "Results.prose"

# Get fence under header
oculus peek jenkins "Config.yaml"

What to build:

  • Enhance peek to support header paths
  • Header tree structure
  • Section-scoped fence access

Phase 3: Format Control ⚡ (HIGH PRIORITY)

Enable output format choice:

# Get node structure as JSON
oculus look jenkins --format json

# Execute fence, get markdown table
oculus execute daily-tasks:TODO list --format markdown

# Peek config as YAML
oculus peek jenkins config --format yaml

What to build:

  • Format parameter on all read operations
  • Formatters: json, yaml, markdown, raw, text
  • Clear separation of mode (processing) vs format (output)

Implementation Checklist

See full checklist in investigation notes, but core items:

Phase 1 (Fence IDs):

  • Fence UUID generation and registry
  • Fence address parser
  • POST /api/oculus/fence/{address}/execute
  • oculus execute <address> <action> --format <fmt>

Phase 2 (Headers):

  • Peek header path support
  • oculus peek <slug> headers
  • oculus peek <slug> "<header>.prose"

Phase 3 (Format):

  • Format parameter on all endpoints
  • Format formatters implementation
  • --format flag on look/peek/execute

Command Consolidation (Phase 6 - Later)

Can wait for v2.0:

  • Consolidate tag commands → peek/poke
  • Consolidate metadata → peek/poke
  • Remove fence group → use execute
  • Split cli.py (3226 lines) → modules

Success Metrics

After Phases 1-3, user experience should be:

# Fast fence execution (no hunting for index)
$ oculus execute daily-tasks:TODO add --content "Review PR" --format json
{"success": true, "item_index": 5, "checked": false}

# Quick header access
$ oculus peek jenkins headers
["## Configuration", "## Pipelines", "### Build Pipeline", "### Deploy Pipeline"]

# Format control
$ oculus look jenkins --format json | jq .metadata.tags
["ci", "jenkins", "infrastructure"]

Fast, direct, no ceremony.

Related Resources

Tags

wanderland, oculus, terminal-velocity