mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Renn F
f48106cbb6
Markdown and editors soft-wrap on their own, so the manual ~75-char line breaks across the docs added nothing but noise. Join wrapped prose, list items, and paragraphs into single lines across 67 docs — README, CLAUDE.md, deployment, usage, the RAG knowledge base, and the agent role prompts. Whitespace-only: code fences, tables, and blockquote alerts are byte-identical and the change is token-verified (no content altered). Applied with a deterministic reflow tool (committed separately). Also lands two doc edits that were awaiting commit: the measured under-load resource numbers in usage.md and the pr_reviewer additions to the org-structure RAG doc.
93 lines
3.0 KiB
Markdown
93 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
|