roboco/docs/rag/workflows/journaling.md

Journaling Workflow

Why Journal

1. Becomes searchable knowledge for future agents
2. Helps with task handoffs
3. Documents decisions and learnings
4. Required before key transitions

Entry Types

Type	Use For
task_reflection	End of task summary
decision_log	Architectural decisions
learning	New knowledge gained
struggle	Problems and solutions
general	Other observations

Creating Entries

# General entry
roboco_journal_entry({
    type: "learning",
    title: "Redis SCAN vs KEYS",
    content: "SCAN is better for large datasets",
    task_id: task_id,
    tags: ["redis", "performance"]
})

# Decision log
roboco_journal_decision({
    title: "Session storage choice",
    context: "Need fast session lookups",
    options: ["PostgreSQL", "Redis", "In-memory"],
    chosen: "Redis",
    rationale: "Sub-millisecond reads, ephemeral data"
})

# Struggle (problem and solution)
roboco_journal_struggle({
    task_id: task_id,
    problem: "Tests failing intermittently",
    attempts: ["Increased timeout", "Added retry"],
    resolution: "Race condition in setup"
})

# Learning
roboco_journal_learning({
    content: "Use asyncio.gather for parallel calls",
    how_applied: "Reduced endpoint latency 50%",
    category: "performance",
    tags: ["async", "performance"]
})

Required Reflections

Before submitting for QA or completing:

roboco_journal_reflect({
    task_id: task_id,
    what_done: "Implemented rate limiting with Redis",
    what_learned: "Lua scripts for atomic operations",
    what_struggled: "Testing concurrent requests"
})

Searching Journals

# Semantic search your journal
roboco_journal_search("rate limiting patterns", top_k=5)

# Search team journals (if permitted)
roboco_journal_read_team("be-dev-1", task_id=task_id)

Best Practices

1. Journal as you go - Don't wait until end
2. Be specific - Generic entries are less searchable
3. Use tags - Helps categorization
4. Record failures - They're valuable learning
5. Include context - Future searchers need it