mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Renn F
ecea593a51
The RAG knowledge base (indexed and queried by agents at runtime) described entire fictional MCP tool surfaces — roboco_task_*, roboco_journal_*, roboco_message_send, roboco_notify_send, roboco_agent_*, roboco_session_*, roboco_workspace_*, roboco_project_* — that don't exist, so agents searching the KB were handed invented tool names. Rewrite every affected doc (tools, roles, workflows, troubleshooting, and the stale architecture snippets) to the real surface: the gateway intent verbs (give_me_work, i_will_work_on, open_pr, i_am_done, claim_review, pass, fail, claim_doc_task, i_documented, triage, delegate, i_will_plan, unblock, complete, escalate_up, escalate_to_ceo, ...) and content tools (commit, note(scope=...), say, dm, evidence, notify*, open_session, channels). Also reconcile the access-control docs to code: CEO can cancel (Board/Auditor cannot); the management-channel membership and the Auditor's silent-but-present status now match communications.py.
98 lines
3.0 KiB
Markdown
98 lines
3.0 KiB
Markdown
# 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
|
|
|
|
## The Tool
|
|
|
|
Journaling is a single content tool: `note(text, scope, ...)` on the
|
|
`roboco-do` MCP server. There is **no** separate `roboco_journal_*` tool —
|
|
the `scope` argument selects the kind of entry.
|
|
|
|
| `scope` | Use For |
|
|
|---------|---------|
|
|
| `note` (default) | General observation |
|
|
| `reflect` | End-of-task summary (what done / learned / struggled) |
|
|
| `decision` | Architectural decision (context / options / chosen / rationale) |
|
|
| `learning` | New knowledge gained |
|
|
| `struggle` | Problems and solutions |
|
|
|
|
## Creating Entries
|
|
|
|
```python
|
|
# General entry
|
|
note(
|
|
text="SCAN is better than KEYS for large Redis datasets",
|
|
scope="learning",
|
|
task_id=task_id,
|
|
)
|
|
|
|
# Decision log — `decision` scope uses the structured fields
|
|
note(
|
|
text="Chose Redis for session storage",
|
|
scope="decision",
|
|
task_id=task_id,
|
|
context="Need fast session lookups, ephemeral data",
|
|
options=[
|
|
{"name": "PostgreSQL", "pros": "durable", "cons": "slower"},
|
|
{"name": "Redis", "pros": "sub-ms reads", "cons": "ephemeral"},
|
|
{"name": "In-memory", "pros": "fastest", "cons": "lost on restart"},
|
|
],
|
|
chosen="Redis",
|
|
rationale="Sub-millisecond reads; data is ephemeral by design",
|
|
consequences=["Adds Redis as a session dependency"],
|
|
)
|
|
|
|
# Struggle (problem and solution)
|
|
note(
|
|
text="Tests failing intermittently; root cause was a setup race condition",
|
|
scope="struggle",
|
|
task_id=task_id,
|
|
)
|
|
```
|
|
|
|
`options`, `consequences`, and `next_steps` accept either a list or a
|
|
single value. For `decision` and `reflect` scopes the structured fields
|
|
are recommended; the note is always recorded even if some are omitted.
|
|
|
|
## Required Reflections
|
|
|
|
Before submitting for QA or completing, write a `reflect` entry:
|
|
|
|
```python
|
|
note(
|
|
text="Implemented rate limiting with Redis",
|
|
scope="reflect",
|
|
task_id=task_id,
|
|
what_done="Redis-backed token bucket on the API edge",
|
|
what_learned="Lua scripts give atomic check-and-decrement",
|
|
what_struggled="Testing concurrent requests deterministically",
|
|
next_steps=["Add a regression test for the boundary case"],
|
|
)
|
|
```
|
|
|
|
## Searching Journals
|
|
|
|
Journal entries are indexed into the knowledge base. Search them through
|
|
the `roboco-optimal` RAG tools (there is no dedicated journal-search verb):
|
|
|
|
```python
|
|
# Semantic search across the KB, filtered to journal entries
|
|
roboco_kb_search(query="rate limiting patterns", index_types=["journals"])
|
|
|
|
# Or ask the mentor, which searches all sources including journals
|
|
roboco_ask_mentor(question="What did we decide about rate limiting?")
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Journal as you go** - Don't wait until end
|
|
2. **Be specific** - Generic entries are less searchable
|
|
3. **Record failures** - They're valuable learning (`scope="struggle"`)
|
|
4. **Use the right scope** - `decision` / `reflect` light up the panel views
|
|
5. **Include context** - Future searchers need it
|