# 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.*