mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Renn F
3441e37120
Post-audit sweep over the 135 audit-fix commits since19a474d3: 1. Stripped every # Fxxx: audit-ID token from comments AND every Fxxx token from docstring openings across 211 blocks / ~626 lines. The CEO flagged these twice: audit-issue IDs in code confuse future devs/agents. The descriptive text is preserved; only the Fxxx token is removed (and bloated narrative blocks trimmed to 1-3 lines keeping the one non-obvious invariant). 2. Trimmed bloated comments/docstrings to the concise standard (1-3 lines). 3. Added missing behavior-change docs for the audit-fix batch: prompts/roles (documenter, pr_reviewer, qa), user-facing docs (api auth, websockets, agent-gateway, megatask, merge-model, task-lifecycle, grok, resilience, conventions, panel, security, troubleshooting), and the RAG corpus (cell-pm, main-pm, pr-reviewer, qa roles; conventions; messaging-tools; escalation; megatask; task-claiming workflows). Comment/docstring/prose ONLY — zero code-line edits (verified: the diff contains no def/class/return/if/for/await/assignment/call lines). Gates green: ruff format + ruff check clean, mypy clean on roboco/. The only pytest failures are the pre-existing sync_branch tracing-decision gap (B1,250be5c2) — not sweep-caused and tracked separately.
85 lines
3.2 KiB
Markdown
85 lines
3.2 KiB
Markdown
# Task Claiming Workflow
|
|
|
|
## Who Can Claim What
|
|
|
|
| Role | Claim verb | Can Claim From Status |
|
|
|------|------------|----------------------|
|
|
| Developer | `i_will_work_on` | `pending`, `needs_revision` |
|
|
| QA | `claim_review` | `awaiting_qa` |
|
|
| Documenter | `claim_doc_task` | `awaiting_documentation`, `pending` |
|
|
| PM | `triage` / `give_me_work` | `pending` |
|
|
|
|
## Claiming a Task
|
|
|
|
```python
|
|
# 1. Get a task assigned to you (returns a pending/awaiting task)
|
|
give_me_work()
|
|
|
|
# 2. Claim it. The claim verb is role-specific:
|
|
i_will_work_on(task_id) # Developer — claims + auto-creates the branch
|
|
claim_review(task_id) # QA — claims + auto-checks-out the dev's branch
|
|
claim_doc_task(task_id) # Documenter
|
|
|
|
# Result:
|
|
# - status: claimed (then in_progress)
|
|
# - assigned_to: your agent ID
|
|
```
|
|
|
|
The claim verb both claims and starts the task — there is no separate `start` call. For developers, `i_will_work_on` also creates and checks out the `feature/{team}/{task-hierarchy}` branch.
|
|
|
|
## Before Claiming
|
|
|
|
1. Check you have capacity (developers / QA / documenters work one task at a time; **PM coordinators are exempt** — a Main / Cell PM may hold many roots at once, gated only by sequence dependencies)
|
|
2. Verify dependencies are completed
|
|
3. Read task description and acceptance criteria
|
|
|
|
## After Claiming
|
|
|
|
1. Announce to your cell: `say(channel="backend-cell", text="...", task_id=task_id)`
|
|
2. Get proactive context: `roboco_get_proactive_context(task_id)`
|
|
3. Search the KB for similar work: `roboco_kb_search(query="...")`
|
|
|
|
## Claiming Rules
|
|
|
|
- **One at a time (workers only)**: Developers, QA, and documenters can't hold multiple in-progress tasks at once. A **blocked** task still counts as active — a blocked dev cannot `claim` a second task; unblock or `unclaim` first. **PM coordinators are exempt** — a Main / Cell PM plans and delegates many roots in parallel, so it may hold several at once; only a real upstream **sequence dependency** (an unfinished task it depends on) holds one of its roots back.
|
|
- **Self-review prevention**: QA cannot `claim_review` tasks they developed
|
|
- **Self-documentation prevention**: Documenter cannot claim tasks they developed
|
|
- **Branch requirement**: Branch auto-created on `i_will_work_on`
|
|
|
|
## Releasing a Claimed Task
|
|
|
|
If you claimed a task but realize you shouldn't work on it, use `unclaim`:
|
|
|
|
```python
|
|
# Release back to pool
|
|
unclaim(task_id)
|
|
|
|
# Result:
|
|
# - status: pending
|
|
# - assigned_to: None
|
|
# - You can now claim new work
|
|
```
|
|
|
|
`unclaim` takes only the `task_id` — it returns the task to the pool for re-pickup. To hand a specific task to a specific agent, escalate to your PM (`escalate_up`) and let the PM re-`delegate` or reassign it.
|
|
|
|
**When to use unclaim:**
|
|
- Task is out of your team's scope
|
|
- Task requires a different role
|
|
- You need to prioritize other work
|
|
- Better suited for another agent
|
|
|
|
## Status After Claim
|
|
|
|
```
|
|
pending → claimed (Developer via i_will_work_on / PM)
|
|
needs_revision → claimed (Developer via i_will_work_on)
|
|
awaiting_qa → claimed (QA via claim_review)
|
|
awaiting_documentation → claimed (Documenter via claim_doc_task)
|
|
```
|
|
|
|
## Cannot Claim
|
|
|
|
- `completed` or `cancelled` (terminal states)
|
|
- Tasks assigned to others
|
|
- Tasks you cannot work on (wrong role/team)
|