mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
docs(rag): rewrite the KB docs to the real gateway verb surface
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.
This commit is contained in:
Renn F
@@ -1,92 +1,121 @@
|
||||
# Journal Tools
|
||||
|
||||
## Creating Entries
|
||||
There is **no** `roboco_journal_*` tool. Journaling is a single content
|
||||
tool on the `roboco-do` MCP server: `note`. The `scope` argument selects
|
||||
the entry kind; structured fields are filled per scope.
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `roboco_journal_entry` | General entry |
|
||||
| `roboco_journal_decision` | Decision log |
|
||||
| `roboco_journal_learning` | Learning capture |
|
||||
| `roboco_journal_struggle` | Problem/solution |
|
||||
| `roboco_journal_reflect` | Task reflection |
|
||||
```python
|
||||
note(
|
||||
text: str, # always: one-paragraph summary
|
||||
scope: str = "note", # note | decision | reflect | learning | struggle
|
||||
task_id: str | None = None, # auto-filled from your active task if omitted
|
||||
title: str | None = None,
|
||||
# decision-scope fields:
|
||||
context: str = "",
|
||||
options=None, # list of {name, pros, cons} (a single dict is ok)
|
||||
chosen: str = "",
|
||||
rationale: str = "",
|
||||
consequences=None, # list of strings (a single string is ok)
|
||||
# reflect-scope fields:
|
||||
what_done: str = "",
|
||||
what_learned: str = "",
|
||||
what_struggled: str = "",
|
||||
next_steps=None, # list of strings (a single string is ok)
|
||||
)
|
||||
```
|
||||
|
||||
`text` is always required. Missing narrative fields default to a visible
|
||||
placeholder rather than being rejected — the note is always recorded.
|
||||
|
||||
## Scopes
|
||||
|
||||
| Scope | Use For | Structured fields |
|
||||
|-------|---------|-------------------|
|
||||
| `note` | General entry | (just `text`) |
|
||||
| `decision` | Decision log | `context`, `options`, `chosen`, `rationale`, `consequences` |
|
||||
| `reflect` | Task reflection | `what_done`, `what_learned`, `what_struggled`, `next_steps` |
|
||||
| `learning` | Learning capture | (just `text`) |
|
||||
| `struggle` | Problem / blocker | (just `text`) |
|
||||
|
||||
## General Entry
|
||||
|
||||
```python
|
||||
roboco_journal_entry({
|
||||
type: "learning",
|
||||
title: "Redis SCAN vs KEYS",
|
||||
content: "SCAN is better for large datasets",
|
||||
task_id: task_id,
|
||||
tags: ["redis", "performance"]
|
||||
})
|
||||
note(
|
||||
text="SCAN is better than KEYS for large datasets",
|
||||
scope="learning",
|
||||
title="Redis SCAN vs KEYS",
|
||||
task_id=task_id,
|
||||
)
|
||||
```
|
||||
|
||||
Entry types: `task_reflection`, `decision_log`, `learning`, `struggle`, `general`
|
||||
|
||||
## Decision Log
|
||||
|
||||
```python
|
||||
roboco_journal_decision({
|
||||
title: "Session storage choice",
|
||||
context: "Need fast session lookups",
|
||||
options: ["PostgreSQL", "Redis"],
|
||||
chosen: "Redis",
|
||||
rationale: "Sub-ms reads, ephemeral data"
|
||||
})
|
||||
note(
|
||||
text="Chose Redis for session storage over PostgreSQL.",
|
||||
scope="decision",
|
||||
title="Session storage choice",
|
||||
context="Need fast session lookups",
|
||||
options=[
|
||||
{"name": "PostgreSQL", "pros": "durable", "cons": "slower reads"},
|
||||
{"name": "Redis", "pros": "sub-ms reads", "cons": "ephemeral"},
|
||||
],
|
||||
chosen="Redis",
|
||||
rationale="Sub-ms reads, ephemeral data",
|
||||
consequences=["Session loss on Redis restart is acceptable"],
|
||||
)
|
||||
```
|
||||
|
||||
## Learning
|
||||
|
||||
```python
|
||||
roboco_journal_learning({
|
||||
content: "asyncio.gather for parallel calls",
|
||||
how_applied: "Reduced latency 50%",
|
||||
category: "performance",
|
||||
tags: ["async"]
|
||||
})
|
||||
note(
|
||||
text="asyncio.gather for parallel calls — reduced latency 50%",
|
||||
scope="learning",
|
||||
title="Parallel async calls",
|
||||
)
|
||||
```
|
||||
|
||||
## Struggle (Problem/Solution)
|
||||
## Struggle (Problem / Blocker)
|
||||
|
||||
```python
|
||||
roboco_journal_struggle({
|
||||
task_id: task_id,
|
||||
problem: "Tests failing intermittently",
|
||||
attempts: ["Timeout increase", "Retry logic"],
|
||||
resolution: "Race condition in setup"
|
||||
})
|
||||
note(
|
||||
text=(
|
||||
"Tests failing intermittently — tried timeout increase and retry "
|
||||
"logic; root cause was a race condition in setup."
|
||||
),
|
||||
scope="struggle",
|
||||
task_id=task_id,
|
||||
)
|
||||
```
|
||||
|
||||
## Reflection (Required)
|
||||
## Reflection
|
||||
|
||||
Use a `reflect`-scope note before submitting to QA — it gives QA the
|
||||
"why" behind the diff.
|
||||
|
||||
```python
|
||||
roboco_journal_reflect({
|
||||
task_id: task_id,
|
||||
what_done: "Implemented rate limiting",
|
||||
what_learned: "Lua scripts for atomicity",
|
||||
what_struggled: "Testing concurrency"
|
||||
})
|
||||
note(
|
||||
text="Implemented rate limiting with a Redis-backed sliding window.",
|
||||
scope="reflect",
|
||||
task_id=task_id,
|
||||
what_done="Implemented rate limiting",
|
||||
what_learned="Lua scripts give atomicity for the counter increment",
|
||||
what_struggled="Testing concurrency deterministically",
|
||||
next_steps=["Add a load test for the 100-req boundary"],
|
||||
)
|
||||
```
|
||||
|
||||
## Reading Journals
|
||||
|
||||
Journals are written by `note` and surface through the knowledge base —
|
||||
there is no separate journal-read tool. Search past notes (yours and
|
||||
your team's, where permitted) via the `roboco-optimal` MCP server:
|
||||
|
||||
```python
|
||||
# Search your journal
|
||||
roboco_journal_search("rate limiting", top_k=5)
|
||||
# Semantic search over indexed notes/decisions/learnings
|
||||
roboco_kb_search(query="rate limiting", index_types=["journals", "decisions"])
|
||||
|
||||
# Recent entries
|
||||
roboco_journal_recent(limit=10)
|
||||
|
||||
# Read team journals (if permitted)
|
||||
roboco_journal_read_team(
|
||||
target_agent="be-dev-1",
|
||||
task_id=task_id
|
||||
)
|
||||
|
||||
# Your stats
|
||||
roboco_journal_stats()
|
||||
|
||||
# Check access scope
|
||||
roboco_journal_scope()
|
||||
# Conversational lookup with follow-up context
|
||||
roboco_ask_mentor(question="What did we decide about session storage?")
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user