4.3 KiB

Raw Blame History

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

./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:

# 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

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

4.3 KiB Raw Blame History