diff --git a/docs/WORKFLOW-IMPROVEMENTS.md b/docs/WORKFLOW-IMPROVEMENTS.md
new file mode 100644
index 0000000..21edab5
--- /dev/null
+++ b/docs/WORKFLOW-IMPROVEMENTS.md
@@ -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.*