External/roboco
1
0
Fork 0
mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: reflow hard-wrapped prose to one line per paragraph

Browse Source 
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.
This commit is contained in:
Renn F
2026-06-16 23:18:55 +02:00
parent 640a964b88
commit f48106cbb6
67 changed files with 504 additions and 1593 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/rag/troubleshooting/git-errors.md
+26 -56
View File
@@ -2,120 +2,90 @@
## Missing Git Token
**Error:** `Project requires a git token for HTTPS repositories`
(also surfaces as `WorkspaceError` during clone)
**Error:** `Project requires a git token for HTTPS repositories` (also surfaces as `WorkspaceError` during clone)
**Cause:** No encrypted GitHub PAT on
`projects.git_token_encrypted` for this project.
**Cause:** No encrypted GitHub PAT on `projects.git_token_encrypted` for this project.
**Fix:**
1. Open the project's settings tab in the panel
2. Paste a GitHub Personal Access Token with `repo` scope
3. Save — the panel encrypts and stores it; the API never returns
the plaintext
3. Save — the panel encrypts and stores it; the API never returns the plaintext
Notes:
- Each project has its own token (no global fallback)
- Tokens are encrypted at rest with Fernet
- The token is injected only at the MCP layer (commit / clone / PR ops);
`.git/config` is scrubbed post-clone so a leaked PAT from there is
not a recovery path
- The token is injected only at the MCP layer (commit / clone / PR ops); `.git/config` is scrubbed post-clone so a leaked PAT from there is not a recovery path
## Workspace Not Found
**Error:** `Workspace does not exist`
**Cause:** Workspace not cloned yet (or `ROBOCO_WORKSPACE_AUTO_CLONE`
is `false` and no manual clone has run).
**Cause:** Workspace not cloned yet (or `ROBOCO_WORKSPACE_AUTO_CLONE` is `false` and no manual clone has run).
**Fix:**
- If `ROBOCO_WORKSPACE_AUTO_CLONE=true` (default), the first MCP verb
that touches the workspace will trigger the clone. Just call your
next verb (`i_will_work_on`, `commit`, etc.).
- Otherwise check `ROBOCO_WORKSPACE_CLONE_TIMEOUT` and the
orchestrator logs for a stuck clone.
- If `ROBOCO_WORKSPACE_AUTO_CLONE=true` (default), the first MCP verb that touches the workspace will trigger the clone. Just call your next verb (`i_will_work_on`, `commit`, etc.).
- Otherwise check `ROBOCO_WORKSPACE_CLONE_TIMEOUT` and the orchestrator logs for a stuck clone.
## BRANCH_MISMATCH
**Error envelope:**
`Workspace is on '<other-branch>' but task requires '<task-branch>'`
**Error envelope:** `Workspace is on '<other-branch>' but task requires '<task-branch>'`
**Cause:** You're trying to act on task A while your workspace is still
on task B's branch.
**Cause:** You're trying to act on task A while your workspace is still on task B's branch.
**Fix:** Don't checkout by hand — there is no `roboco_git_checkout`
tool. Call the verb on the *intended* task instead:
**Fix:** Don't checkout by hand — there is no `roboco_git_checkout` tool. Call the verb on the *intended* task instead:
- Devs: `i_will_work_on(task_id)` switches to that task's branch
- PMs: `i_will_plan(task_id, plan)` switches to that parent task's
branch
- PMs: `i_will_plan(task_id, plan)` switches to that parent task's branch
- QA: `claim_review(task_id)` switches to the dev's branch under review
If your workspace is dirty, the verb returns an envelope telling you to
either `commit(...)` first or escalate via `i_am_blocked`.
If your workspace is dirty, the verb returns an envelope telling you to either `commit(...)` first or escalate via `i_am_blocked`.
## NO_COMMITS on open_pr
**Cause:** No commits on the task yet — the choreographer has nothing
to open a PR over.
**Cause:** No commits on the task yet — the choreographer has nothing to open a PR over.
**Fix:** `commit(message=..., files=...)` at least once, then call
`open_pr(task_id)` again.
**Fix:** `commit(message=..., files=...)` at least once, then call `open_pr(task_id)` again.
## NO_PR on pass / fail
**Cause:** The PR was never created — usually because
`open_pr(task_id)` did not run cleanly.
**Cause:** The PR was never created — usually because `open_pr(task_id)` did not run cleanly.
**Fix:** Roll back to the dev: have them re-call `open_pr(task_id)`
after fixing whatever blocked the PR opening (see PR Creation Failed,
below). QA cannot create the PR.
**Fix:** Roll back to the dev: have them re-call `open_pr(task_id)` after fixing whatever blocked the PR opening (see PR Creation Failed, below). QA cannot create the PR.
## PR Creation Failed (during open_pr)
**Causes:**
1. Nothing to push — no commits on the branch
2. Branch is on the workspace but not pushed yet (rare; the choreographer
pushes during `commit`, but a stale workspace can drift)
2. Branch is on the workspace but not pushed yet (rare; the choreographer pushes during `commit`, but a stale workspace can drift)
3. Project has no git token configured
4. The GitHub repo doesn't allow PRs from your branch (rare; usually
org-level branch protection)
4. The GitHub repo doesn't allow PRs from your branch (rare; usually org-level branch protection)
**Fix:**
- Verify commits exist with `roboco_git_log(project_slug=...)`
- Verify the project has a git token (Missing Git Token, above)
- If the task is in a stuck state, `unclaim(task_id)` and re-`claim`
to rebuild the branch
- If the task is in a stuck state, `unclaim(task_id)` and re-`claim` to rebuild the branch
## FORCE_PUSH_FORBIDDEN
**Cause:** Force-push is CEO-only. Anyone else attempting it (typically
because their branch diverged) is denied.
**Cause:** Force-push is CEO-only. Anyone else attempting it (typically because their branch diverged) is denied.
**Fix:** `unclaim(task_id)` and re-`claim` it. The choreographer
rebuilds the branch from the parent's HEAD; replay your commits with
`commit(...)`.
**Fix:** `unclaim(task_id)` and re-`claim` it. The choreographer rebuilds the branch from the parent's HEAD; replay your commits with `commit(...)`.
## Merge Conflicts on `complete`
**Cause:** The leaf PR conflicts with the parent branch (cell branch
or master).
**Cause:** The leaf PR conflicts with the parent branch (cell branch or master).
**Fix:** This currently surfaces as an error envelope from `complete`.
The recovery path:
**Fix:** This currently surfaces as an error envelope from `complete`. The recovery path:
1. PM `unblock(task_id, restore=False)` — frees the task back to the
dev
2. Dev re-claims, the choreographer rebuilds the branch off the latest
parent, and they replay their commits
1. PM `unblock(task_id, restore=False)` — frees the task back to the dev
2. Dev re-claims, the choreographer rebuilds the branch off the latest parent, and they replay their commits
3. Dev `open_pr` again
4. QA re-runs `pass` (or `fail` if the rebase changed behaviour)
5. PM `complete` again
We don't expose a "resolve conflicts in place" path at the agent layer
— rebuilds via the lifecycle are the recovery.
We don't expose a "resolve conflicts in place" path at the agent layer — rebuilds via the lifecycle are the recovery.