Gentle Guidance 🌱

The teaching side of competent computing: show how to use the sharp tools.

---

Core Belief

Sharp tools deserve clear instructions.

Competent computing gives you sharp tools and trusts you to use them. Gentle guidance ensures you know how to use them well. Not hand-holding - teaching.

---

The Pattern

When something "just works if you do it right," document the right way:

Competent Computing	Gentle Guidance
"Send it right or it gets fucky"	"Here's how to send it right"
No heuristics, no guessing	Clear examples of correct usage
Mistakes are recoverable	Mistakes are preventable
Sharp tools	Clear instructions

---

Tips & Gotchas

Auto-Provenance Injection ✅ AUTO-FIXED

Status: Implemented in graph_api_ast.py:enable_provenance_auto_injection()

When saving a node with code fences but no provenance section, Oculus automatically injects one.

The Problem: Nodes with executable fences have no verification tracking.

The Auto-Fix: On save, if fences exist but no ## Provenance section:

• Empty provenance section auto-injected
• Each fence gets an unverified (🔴) entry
• Ready for verification workflow

Competent computing says: "No provenance? That's on you." Gentle guidance says: "We auto-add it. Ready when you need it."

Note: Priority 55 - runs after slot normalization, before index updates.

Duplicate Slot Entries ✅ AUTO-FIXED

Status: Implemented in ast_converter.py:193-206

When linking nodes via slots, AIs sometimes accidentally add the same slug multiple times:

The Problem:

slots:
- slug: competent-computing
  context: []
- slug: competent-computing    ← Duplicate!
  context: ["new context"]

The Auto-Fix: Oculus now automatically normalizes slot fences on save:

• Duplicates are merged (same slug → single entry)
• Contexts are combined (new context entries added to existing)
• Original order preserved

Competent computing says: "Add duplicates, they duplicate." Gentle guidance says: "We auto-merge them. You don't have to clean up."

Note: Fix applies on any poke operation that touches the node.

---

Nested Markdown Fences ✅ AUTO-FIXED

Status: Implemented in ast_converter.py:142-148 Tests: gentle-guidance-test

When writing documentation that contains code block examples, inner fences can break outer fences.

The Auto-Fix: Oculus now automatically upgrades markdown and md fences to 4 backticks on save.

Competent computing says: "Nest your fences wrong, they break." Gentle guidance says: "We auto-fix it. You don't have to remember."

---

Adding Tips

When you discover a gotcha that:

• Has a clear "right way" to do it
• Isn't obvious from the error message
• Applies across the system

Add it here. Format:

### [Short Title]

**The Problem:** What goes wrong

**The Solution:** How to do it right

**Why this matters:** Where you'll encounter this

**Competent/Gentle framing:** The philosophy connection

---

Related Nodes

• competent-computing - The sharp tools philosophy
• pattern-gentle-error-messaging - How errors teach
• wanderland-philosophy - The empathetic computing side

---

North

slots:
- slug: wanderland-philosophy
  context: []

South

slots:
- context: []
  slug: loading-screen-tips
- context: []
  slug: gentle-guidance-test
- context:
  - Teaching moment is child of gentle-guidance philosophy
  slug: toodles-teaching-moment

East

slots:
- slug: competent-computing
  context: []
- slug: pattern-competent-computing
  context: []

West

slots:
- slug: pattern-gentle-error-messaging
  context: []