roboco/docs/workflows/JOURNALING.md

Journaling Guide

Status: Implemented

This document describes the Journal API and how agents use it for personal growth tracking.

---

Purpose

Your journal is your personal growth record. It:

• Documents your decision-making process
• Tracks what you learned
• Records struggles for future reference
• Creates institutional memory
• Helps documenters understand your journey
• Enables semantic search for past experiences

---

Journal API Endpoints

Your Journal (/me)

Endpoint	Method	Description
/journals/me	GET	Get or create your journal
/journals/me/entries	GET	List your entries
/journals/me/entries	POST	Create a general entry
/journals/me/stats	GET	Get your journal statistics
/journals/me/growth	GET	Get your growth metrics
/journals/me/search	POST	Semantic search your journal
/journals/me/reflections	POST	Add task reflection
/journals/me/decisions	POST	Add decision log
/journals/me/learnings	POST	Add learning entry
/journals/me/struggles	POST	Add struggle entry
/journals/me/notes	POST	Add general note

Other Agent Journals (with permission)

Endpoint	Method	Description
/journals/{agent_id}	GET	Get another agent's journal
/journals/{agent_id}/entries	GET	List another agent's entries
/journals/entries/{entry_id}	GET	Get specific entry
/journals/entries/{entry_id}	DELETE	Delete your own entry

---

Journal Entry Types

1. General Entry

Basic logging for day-to-day work:

roboco_journal_entry({
    "type": "work_log",           # or "note", "observation"
    "title": "Started rate limiter implementation",
    "content": "Reviewing existing code patterns in auth module...",
    "task_id": "uuid-here",       # Link to current task
    "session_id": "uuid-here",    # Link to session (optional)
    "tags": ["rate-limiting", "redis"],
    "is_private": false           # Default: false
})

When to use:

• Starting work on a task
• Mid-task progress notes
• Observations about the codebase
• General thoughts

---

2. Decision Log

RECOMMENDED when choosing between approaches:

roboco_journal_decision({
    "title": "Chose Redis over in-memory for rate limiting",
    "context": "Need to implement rate limiting for API endpoints",
    "options": [
        "Redis sliding window",
        "In-memory with TTL",
        "Database-backed counter"
    ],
    "chosen": "Redis sliding window",
    "rationale": "Redis provides distributed state, TTL support, and scales horizontally. In-memory wouldn't work with multiple instances.",
    "consequences": "Added Redis dependency, need to handle connection failures",
    "task_id": "uuid-here",
    "tags": ["architecture", "rate-limiting"]
})

When to use:

• Choosing between libraries/frameworks
• Architecture decisions
• Implementation approach selection
• Trade-off decisions

---

3. Task Reflection

RECOMMENDED when completing a task:

roboco_journal_reflect({
    "task_id": "uuid-here",
    "title": "Rate Limiter Implementation Complete",
    "what_done": "Implemented Redis-based sliding window rate limiter with configurable limits per endpoint",
    "what_learned": "Redis MULTI/EXEC for atomic operations, Lua scripting for complex logic",
    "what_struggled": "Initially missed edge case with concurrent requests - had to add locking",
    "next_steps": "Consider adding rate limit headers to responses, document in API docs",
    "tags": ["implementation", "rate-limiting"]
})

When to use:

• After submitting for QA
• After completing any significant task
• When handing off to documenter

---

4. Learning Entry

Document new knowledge:

roboco_journal_learning({
    "title": "Redis Lua Scripting for Atomic Operations",
    "what_learned": "Redis Lua scripts execute atomically - no need for separate locking when using EVAL",
    "how_applied": "Used in rate limiter to check and increment in single atomic operation",
    "source": "Redis documentation + trial and error",
    "task_id": "uuid-here",
    "tags": ["redis", "lua", "atomic-operations"]
})

When to use:

• Discovered something new about a technology
• Found a better pattern
• Learned from a mistake
• Picked up domain knowledge

---

5. Struggle Entry

Document challenges for future reference:

roboco_journal_struggle({
    "title": "Race condition in concurrent rate limit checks",
    "what_struggled": "Multiple requests hitting rate limiter simultaneously were all passing before any count incremented",
    "attempted_solutions": [
        "Added Redis WATCH - didn't help with high concurrency",
        "Tried INCR with separate GET - still had race window"
    ],
    "resolution": "Used Lua script to make check+increment atomic",
    "help_needed": false,
    "task_id": "uuid-here",
    "tags": ["race-condition", "concurrency", "redis"]
})

When to use:

• Hit a blocker (even if resolved)
• Spent significant time debugging
• Found a non-obvious solution
• Need to request help (help_needed: true)

---

When to Journal

Moment	Entry Type	Tool
Start a task	General entry	roboco_journal_entry
Make a decision	Decision log	roboco_journal_decision
Learn something new	Learning	roboco_journal_learning
Hit a struggle	Struggle	roboco_journal_struggle
Complete a task	Reflection	roboco_journal_reflect
Make progress	General entry	roboco_journal_entry
Quick note	General note	roboco_journal_entry

---

Reading Journals

Search Your Own Journal

Semantic search (uses RAG):

roboco_journal_search({
    "query": "rate limiting redis",
    "top_k": 5
})

List Your Entries

# Recent entries
roboco_journal_recent(limit=10)

# Filter by type
roboco_journal_recent(entry_type="decision_log")

# Filter by task
roboco_journal_recent(task_id="uuid-here")

Your Statistics

roboco_journal_stats()
# Returns: total_entries, entries_by_type, last_entry_at, has_summary

Your Growth Metrics

roboco_journal_growth()
# Returns:
#   total_reflections, total_learnings, total_struggles, total_decisions,
#   struggle_resolution_rate, learning_frequency, sentiment_trend

---

Reading Other Agents' Journals

Access is based on cell membership and role hierarchy:

# By agent slug
roboco_journal_read("be-dev-1")

# By agent UUID
roboco_journal_read("a1b2c3d4-...")

# List entries with filters
roboco_journal_read_entries(
    agent_id="be-dev-1",
    entry_type="decision_log",
    task_id="uuid-here",
    limit=10
)

---

Access Permissions

The Journal API enforces strict access controls based on cell membership:

Your Role	Can Read Journals Of
Developer	Own only
QA	Own only
Documenter	Own + cell members (for documentation)
Cell PM	Own + cell members
Main PM	Own + all Cell PMs
Auditor	Everyone (silent observer)
CEO	Everyone

Cell Membership

• Backend Cell: be-dev-1, be-dev-2, be-qa, be-pm, be-doc
• Frontend Cell: fe-dev-1, fe-dev-2, fe-qa, fe-pm, fe-doc
• UX/UI Cell: ux-dev-1, ux-dev-2, ux-qa, ux-pm, ux-doc

Cell members with access can see ALL entries from each other, including private ones.

---

Private Entries

Mark entries as private when they contain sensitive reflections:

roboco_journal_entry({
    "type": "observation",
    "title": "Personal note on team dynamics",
    "content": "...",
    "is_private": true
})

Note: Cell members with journal access can see your private entries. This is by design - journals are for team learning, not secrets.

---

Entry Response Format

All entry endpoints return:

{
    "id": "uuid",
    "journal_id": "uuid",
    "type": "decision_log",
    "title": "...",
    "content": "...",
    "task_id": "uuid or null",
    "session_id": "uuid or null",
    "timestamp": "2025-01-15T10:30:00Z",
    "tags": ["tag1", "tag2"],
    "sentiment": "positive|neutral|negative|null",
    "is_private": false,
    "created_at": "...",
    "updated_at": "..."
}

---

Best Practices

1. Journal as you go - Don't wait until end of task
2. Include task_id - Links entries to work for context
3. Be specific - Future you needs context
4. Record failures - Struggles are valuable learning
5. Reflect honestly - No one judges your struggles
6. Tag consistently - Helps with search and filtering
7. Use structured types - Decision logs, reflections, learnings are searchable
8. Link sessions - Include session_id when working in a session

---

Integration with Task Workflow

On Claim

roboco_journal_entry({
    "type": "work_log",
    "title": f"Claimed task: {task.title}",
    "content": "Initial assessment: ...",
    "task_id": task_id
})

On Decision

roboco_journal_decision({
    "title": "Implementation approach",
    "context": "...",
    "options": [...],
    "chosen": "...",
    "rationale": "...",
    "task_id": task_id
})

On Completion

roboco_journal_reflect({
    "task_id": task_id,
    "title": f"Completed: {task.title}",
    "what_done": "...",
    "what_learned": "...",
    "what_struggled": "...",
    "next_steps": "..."
})

---

Growth Metrics Explained

The growth metrics endpoint tracks your development over time:

Metric	Description
total_reflections	Number of task reflections
total_learnings	Number of learning entries
total_struggles	Number of struggle entries
total_decisions	Number of decision logs
struggle_resolution_rate	% of struggles with resolutions
learning_frequency	Learnings per time period
sentiment_trend	Overall sentiment direction (improving, stable, declining)