mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Renn F
5315e9c72d
Task Management:
- Add cancellation safeguards: require valid reason category (duplicate,
obsolete, blocked_permanently, reassigned, scope_change, stakeholder_request)
- Protect active work from arbitrary cancellation - must pause/block first
- Auto-notify PM when task is blocked with ACTION REQUIRED message
- PM task scan now shows blocked tasks needing their attention
Permissions:
- Add VIEW_STATS to Developer, QA, Documenter, Head Marketing KB permissions
- Aligns code with docs/workflows/PERMISSIONS.md specification
RAG/Embeddings:
- Upgrade embedding model from all-MiniLM-L6-v2 to nomic-embed-text-v1.5
- 768 dimensions with 8K token context (vs 512 tokens)
- Add per-index chunk sizes: docs=1536, journals=1024, others=512
- Switch to fixed chunking (semantic chunking loads separate MiniLM model)
- Add einops dependency required by nomic model
7.9 KiB
7.9 KiB
Documenter Workflow
Overview
Documenters (be-doc, fe-doc, ux-doc) create production documentation from developer work.
┌─────────────────────────────────────────────────────────────────────────┐
│ DOCUMENTER WORKFLOW │
└─────────────────────────────────────────────────────────────────────────┘
1. SCAN FOR WORK
│
│ roboco_task_scan(team="backend")
│
│ Look for:
│ └── Tasks in "awaiting_documentation" status
│
▼
2. CLAIM TASK
│
│ roboco_task_claim(task_id)
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ Documenter can claim: │
│ │ ├── "awaiting_documentation" (normal workflow) │
│ │ └── "pending" (direct docs tasks from PM) │
│ │ │
│ │ AFTER: │
│ │ status: claimed │
│ │ assigned_to: documenter │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
3. START DOCUMENTATION
│
│ roboco_task_start(task_id)
│
│ # REQUIRED: Announce to cell
│ roboco_message_send({
│ channel: "backend-cell",
│ content: "Starting documentation for [task title]",
│ task_id: task_id
│ })
│
│ STATUS: claimed → in_progress
│
▼
4. GATHER CONTEXT
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ REQUIRED - Read dev's journey: │
│ │ roboco_journal_read_team(original_developer, task_id=task_id) │
│ │ │
│ │ Also review: │
│ │ ├── Developer's handoff notes (in quick_context) │
│ │ ├── QA review notes │
│ │ ├── roboco_channel_history("backend-cell") │
│ │ └── roboco_kb_search("similar documentation") │
│ │ │
│ │ Journal what you gathered: │
│ │ roboco_journal_entry({type: "research", ...}) │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
5. WRITE DOCUMENTATION
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ Create: │
│ │ ├── API documentation │
│ │ ├── Usage examples │
│ │ ├── Architecture notes │
│ │ └── Update README if needed │
│ │ │
│ │ REQUIRED - Progress updates: │
│ │ roboco_task_progress(task_id, "Writing API docs", 50) │
│ │ roboco_task_progress(task_id, "Adding examples", 75) │
│ │ │
│ │ REQUIRED - Journal as you write: │
│ │ roboco_journal_entry({type: "documentation", ...}) │
│ │ roboco_journal_decision(...) # For doc structure choices │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
6. REFLECT & INDEX (before completing)
│
│ # REQUIRED: Reflect on documentation work
│ roboco_journal_reflect({
│ task_id: task_id,
│ what_done: "Created X docs with Y examples",
│ what_learned: "Doc patterns for this codebase",
│ what_struggled: "Understanding Z component"
│ })
│
│ # Index your new docs for future search
│ roboco_kb_index_docs(["docs/new-feature.md"])
│
▼
7. COMPLETE DOCUMENTATION
│
│ roboco_task_docs_complete(task_id)
│
│ STATUS: in_progress → awaiting_pm_review
│ ASSIGNED_TO: automatically set to responsible PM
│ NOTIFICATION: sent to PM via Redis Streams
│
▼
DONE (for documenter) → PM receives notification and reviews
Self-Documentation Prevention
┌─────────────────────────────────────────────────────────────────────────┐
│ Documenter CANNOT document tasks they originally developed │
│ │
│ System tracks original_developer in quick_context │
│ If documenter == original_developer → FORBIDDEN │
└─────────────────────────────────────────────────────────────────────────┘
Status Transitions (Documenter perspective)
CAN CLAIM:
awaiting_documentation ──claim──► claimed
pending ─────────────────claim──► claimed (direct docs tasks)
AFTER CLAIM:
claimed ──start──► in_progress
COMPLETE:
in_progress ──docs_complete──► awaiting_pm_review
Using Knowledge Base
Documenters have KB access including doc indexing:
roboco_kb_search("similar documentation") # Find related docs
roboco_rag_query("how is X documented?") # AI-generated answers
roboco_journal_read_team("be-dev-1") # Read developer's journey
# Indexing (Documenter)
roboco_kb_index_docs(["docs/**/*.md"]) # Index your docs for search
See KNOWLEDGE_BASE.md for full documentation.
Key Rules
- Only claim awaiting_documentation or pending - Can't claim dev tasks
- Cannot self-document - Can't document your own dev work
- MESSAGE when starting - Announce to cell channel
- READ dev's journey - roboco_journal_read_team() REQUIRED
- JOURNAL your work - Document decisions, learnings
- REFLECT before submit - roboco_journal_reflect() REQUIRED
- INDEX your docs - roboco_kb_index_docs() for future search
- Quality docs - Future developers depend on this
- Cannot COMPLETE task - Only submits for PM review