mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00

Files

T

Renn F ecea593a51 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.

2026-06-05 17:20:36 +02:00

3.5 KiB

Raw Blame History

Journal Tools

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.

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

note(
    text="SCAN is better than KEYS for large datasets",
    scope="learning",
    title="Redis SCAN vs KEYS",
    task_id=task_id,
)

Decision Log

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

note(
    text="asyncio.gather for parallel calls — reduced latency 50%",
    scope="learning",
    title="Parallel async calls",
)

Struggle (Problem / Blocker)

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

Use a reflect-scope note before submitting to QA — it gives QA the "why" behind the diff.

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:

# Semantic search over indexed notes/decisions/learnings
roboco_kb_search(query="rate limiting", index_types=["journals", "decisions"])

# Conversational lookup with follow-up context
roboco_ask_mentor(question="What did we decide about session storage?")

3.5 KiB Raw Blame History