Capture workflow friction from Hans' first real test session
Real issues found: 1. Daily review script bugs (checker needed checking) 2. Tea CLI auth not documented (had to describe commands) 3. Go module structure confusing (telemetry standalone) 4. Done signal ambiguous (had to ask permission) 5. Build tags not in QUICKSTART 6. Issue state machine undocumented (who closes?) 7. No task pickup skill (had to guess priority) Biggest: Agents can't fully query/modify Gitea programmatically. Options: A) Full autonomy (skills needed), B) Assisted (current), C) Hybrid. Immediate fixes needed in QUICKSTART.md and handbook documentation.
This commit is contained in:
James
parent
b4aced5c03
commit
cd1644128f
|
|
@ -0,0 +1,154 @@
|
|||
# Workflow Improvement Backlog — From Hans' Session
|
||||
|
||||
**Date:** 2026-04-09
|
||||
**Source:** First real agent workflow test (Hans on telemetry issues)
|
||||
|
||||
---
|
||||
|
||||
## 1. Daily Review Script — Self-Test Mode
|
||||
|
||||
**Problem:** Script had bugs (line 177 syntax error, false positives). Hans had to "check the checker."
|
||||
|
||||
**Fix:** Add `--self-test` flag
|
||||
```bash
|
||||
./scripts/daily-review.sh --self-test # Validates script logic without failing
|
||||
./scripts/daily-review.sh --verbose # Shows all grep matches for debugging
|
||||
```
|
||||
|
||||
**Status:** Script fixed in `6d5837c`, but `--self-test` not yet implemented.
|
||||
|
||||
---
|
||||
|
||||
## 2. Tea CLI Authentication — Undocumented
|
||||
|
||||
**Problem:** Remote commands (`issue close`, `assign`) failed. Had to describe commands for user to run.
|
||||
|
||||
**Solutions (pick one):**
|
||||
|
||||
| Option | Implementation | Effort |
|
||||
|--------|---------------|--------|
|
||||
| A | Add to `QUICKSTART.md`: `tea login add --name clavitor --url https://git.clavitor.ai --token $TOKEN` | 5 min |
|
||||
| B | Create `skill name=gitea` with auth handling | 1 hour |
|
||||
| C | Change workflow to PR-based (no issue state changes needed from agents) | 2 hours |
|
||||
|
||||
**Recommendation:** Option A immediately, Option B later.
|
||||
|
||||
---
|
||||
|
||||
## 3. Go Module Structure — Confusing
|
||||
|
||||
**Problem:** Telemetry has its own `go.mod`, not referenced by main vault. Hans created temp files to test.
|
||||
|
||||
**Fix Options:**
|
||||
- Add telemetry to root `go.work` (workspace)
|
||||
- Document: "cd clavis/clavis-telemetry && use its own go.mod"
|
||||
- Add to Makefile: `make test-telemetry`
|
||||
|
||||
**Status:** Needs decision.
|
||||
|
||||
---
|
||||
|
||||
## 4. "Done" Signal — Ambiguous
|
||||
|
||||
**Problem:** After fixing, Hans asked "Want me to commit?" Should be automatic.
|
||||
|
||||
**Fix:** Update `QUICKSTART.md` workflow:
|
||||
```
|
||||
Agent completes work → git add → git commit -m "Fixes #N" → git push → Create PR
|
||||
Wait for reviewer. DO NOT ask permission for each step.
|
||||
```
|
||||
|
||||
**Status:** `QUICKSTART.md` updated, but could be clearer.
|
||||
|
||||
---
|
||||
|
||||
## 5. Build Tags — Not in QUICKSTART
|
||||
|
||||
**Problem:** Had to discover `-tags commercial` was required.
|
||||
|
||||
**Fix:** Add to `QUICKSTART.md`:
|
||||
```bash
|
||||
# Build commercial edition
|
||||
go build -tags commercial .
|
||||
|
||||
# Test telemetry
|
||||
go test -tags commercial ./...
|
||||
```
|
||||
|
||||
**Status:** Not done.
|
||||
|
||||
---
|
||||
|
||||
## 6. Issue State Machine — Undocumented
|
||||
|
||||
**Problem:** Issues stay "open" even with "Fixes #N" in commit. Need manual close.
|
||||
|
||||
**Document Expected Flow:**
|
||||
```
|
||||
Open → Assigned to agent → Fixed in PR ("Fixes #N") → Reviewer approves
|
||||
→ Reviewer closes issue → Done
|
||||
```
|
||||
|
||||
**Not:** Agent closes issue (wrong — reviewer validates fix first)
|
||||
|
||||
**Status:** Not documented.
|
||||
|
||||
---
|
||||
|
||||
## 7. Task Pickup Skill — Missing
|
||||
|
||||
**Problem:** Had to guess which issues to work on. No clear "this is your task" signal.
|
||||
|
||||
**Proposed Skill:** `skill name=tasks`
|
||||
```bash
|
||||
# List my tasks, filtered and prioritized
|
||||
skill name=tasks action=my-queue
|
||||
|
||||
Output:
|
||||
=== Tasks for Hans ===
|
||||
PRIORITY ISSUE TITLE
|
||||
CRITICAL #2 Silent DB errors (Yurii) ← Work on this first
|
||||
CRITICAL #3 Kuma silent failure (Yurii)
|
||||
MEDIUM #1 Missing error codes (Yurii)
|
||||
MEDIUM #4 Tarpit flush error (Yurii)
|
||||
```
|
||||
|
||||
**Status:** Proposed, not implemented.
|
||||
|
||||
---
|
||||
|
||||
## Biggest Issue: Workflow Gap
|
||||
|
||||
**The Problem:** Handbook says "Pick up issue from git.clavitor.ai" but agents can't actually:
|
||||
- Query issues assigned to them programmatically
|
||||
- Change issue state (close, reassign)
|
||||
- Link issues to PRs via CLI
|
||||
|
||||
**Creates friction:** Every agent session requires manual user intervention.
|
||||
|
||||
---
|
||||
|
||||
## Immediate Actions (This Week)
|
||||
|
||||
| Priority | Task | Owner |
|
||||
|----------|------|-------|
|
||||
| P1 | Fix QUICKSTART.md with tea login, build tags, clear "done" workflow | Johan |
|
||||
| P2 | Document issue state machine in handbook | Johan |
|
||||
| P3 | Add telemetry to Makefile or document standalone | Johan |
|
||||
| P4 | Test daily-review.sh with `--self-test` | Charles/Sarah |
|
||||
| P5 | Implement `skill name=tasks` for Gitea | Future |
|
||||
|
||||
---
|
||||
|
||||
## Foundation Question
|
||||
|
||||
Do we want:
|
||||
- **A)** Agents fully autonomous (can query tasks, create PRs, full workflow) — requires skill development
|
||||
- **B)** Agents assisted (describe what to do, user runs commands) — current state, more friction
|
||||
- **C)** Hybrid (agents create local files, user imports to Gitea) — backup plan
|
||||
|
||||
**Current:** Between B and C. Needs decision to reach A.
|
||||
|
||||
---
|
||||
|
||||
*Captured from Hans' first workflow test. Real friction, real fixes needed.*
|
||||
Loading…
Reference in New Issue