# Agent Workflow Analysis

Common agent workflows, round-trip costs, and token profiles.

---

## 1. Common Workflows

### Flow 1: "What should I work on?" — 4 round trips

```
me                            → dashboard overview (which items need attention?)
issues <iid> -p proj         → detail on picked issue (full context + discussions)
trace src/relevant/file.rs    → understand code context (why was it written?)
who src/relevant/file.rs      → find domain experts (who can help?)
```

**Total tokens (minimal):** ~800 + ~2000 + ~1000 + ~400 = ~4200
**Total tokens (full):** ~3000 + ~6000 + ~1500 + ~800 = ~11300
**Latency:** 4 serial round trips

### Flow 2: "What happened with this feature?" — 3 round trips

```
search "feature name"         → find relevant entities
timeline "feature name"       → reconstruct chronological history
related issues 42             → discover connected work
```

**Total tokens (minimal):** ~600 + ~1500 + ~400 = ~2500
**Total tokens (full):** ~2000 + ~5000 + ~1000 = ~8000
**Latency:** 3 serial round trips

### Flow 3: "Why was this code changed?" — 3 round trips

```
trace src/file.rs             → file -> MR -> issue chain
issues <iid> -p proj         → full issue detail
timeline "issue:42"           → full history with cross-refs
```

**Total tokens (minimal):** ~800 + ~2000 + ~1500 = ~4300
**Total tokens (full):** ~1500 + ~6000 + ~5000 = ~12500
**Latency:** 3 serial round trips

### Flow 4: "Is the system healthy?" — 2-4 round trips

```
health                        → quick pre-flight (pass/fail)
doctor                        → detailed diagnostics (if health fails)
status                        → sync state per project
stats                         → document/index health
```

**Total tokens:** ~100 + ~300 + ~200 + ~400 = ~1000
**Latency:** 2-4 serial round trips (often 1 if health passes)

### Flow 5: "Who can review this?" — 2-3 round trips

```
who src/auth/                 → find file experts
who @jdoe --reviews           → check reviewer's patterns
```

**Total tokens (minimal):** ~300 + ~300 = ~600
**Latency:** 2 serial round trips

### Flow 6: "Find and understand an issue" — 4 round trips

```
search "query"                → discover entities (get IIDs)
issues <iid>                  → full detail with discussions
timeline "issue:42"           → chronological context
related issues 42             → connected entities
```

**Total tokens (minimal):** ~600 + ~2000 + ~1500 + ~400 = ~4500
**Total tokens (full):** ~2000 + ~6000 + ~5000 + ~1000 = ~14000
**Latency:** 4 serial round trips

---

## 2. Token Cost Profiles

Measured typical response sizes in robot mode with default settings:

| Command | Typical Tokens (full) | With `--fields minimal` | Dominant Cost Driver |
|---|---|---|---|
| `me` (all sections) | 2000-5000 | 500-1500 | Open items count |
| `issues` (list, n=50) | 1500-3000 | 400-800 | Labels arrays |
| `issues <iid>` (detail) | 1000-8000 | N/A (no minimal for detail) | Discussion depth |
| `mrs <iid>` (detail) | 1000-8000 | N/A | Discussion depth, DiffNote positions |
| `timeline` (limit=100) | 2000-6000 | 800-1500 | Event count + evidence |
| `search` (n=20) | 1000-3000 | 300-600 | Snippet length |
| `who expert` | 300-800 | 150-300 | Expert count |
| `who workload` | 500-1500 | 200-500 | Open items count |
| `trace` | 500-2000 | 300-800 | Chain depth |
| `file-history` | 300-1500 | 200-500 | MR count |
| `related` | 300-1000 | 200-400 | Result count |
| `drift` | 200-800 | N/A | Similarity curve length |
| `notes` (n=50) | 1500-5000 | 500-1000 | Body length |
| `count` | ~100 | N/A | Fixed structure |
| `stats` | ~500 | N/A | Fixed structure |
| `health` | ~100 | N/A | Fixed structure |
| `doctor` | ~300 | N/A | Fixed structure |
| `status` | ~200 | N/A | Project count |

### Key Observations

1. **Detail commands are expensive.** `issues <iid>` and `mrs <iid>` can hit 8000 tokens due to discussions. This is the content agents actually need, but most of it is discussion body text.

2. **`me` is the most-called command** and ranges 2000-5000 tokens. Agents often just need "do I have work?" which is ~100 tokens (summary counts only).

3. **Lists with labels are wasteful.** Every issue/MR in a list carries its full label array. With 50 items x 5 labels each, that's 250 strings of overhead.

4. **`--fields minimal` helps a lot** — 50-70% reduction on list commands. But it's not available on detail views.

5. **Timeline scales linearly** with event count and evidence notes. The `--max-evidence` flag helps cap the expensive part.

---

## 3. Round-Trip Inefficiency Patterns

### Pattern A: Discovery -> Detail (N+1)

Agent searches, gets 5 results, then needs detail on each:

```
search "auth bug"              → 5 results
issues 42 -p proj             → detail
issues 55 -p proj             → detail
issues 71 -p proj             → detail
issues 88 -p proj             → detail
issues 95 -p proj             → detail
```

**6 round trips** for what should be 2 (search + batch detail).

### Pattern B: Detail -> Context Gathering

Agent gets issue detail, then needs timeline + related + trace:

```
issues 42 -p proj             → detail
timeline "issue:42" -p proj   → events
related issues 42 -p proj     → similar
trace src/file.rs -p proj     → code provenance
```

**4 round trips** for what should be 1 (detail with embedded context).

### Pattern C: Health Check Cascade

Agent checks health, discovers issue, drills down:

```
health                         → unhealthy (exit 19)
doctor                         → token OK, Ollama missing
stats --check                  → 5 orphan embeddings
stats --repair                 → fixed
```

**4 round trips** but only 2 are actually needed (doctor covers health).

### Pattern D: Dashboard -> Action

Agent checks dashboard, picks item, needs full context:

```
me                             → 5 open issues, 2 MRs
issues 42 -p proj             → picked issue detail
who src/auth/ -p proj         → expert for help
timeline "issue:42" -p proj   → history
```

**4 round trips.** With `--include`, could be 2 (me with inline detail + who).

---

## 4. Optimized Workflow Vision

What the same workflows look like with proposed optimizations:

### Flow 1 Optimized: "What should I work on?" — 2 round trips

```
me --depth titles              → 400 tokens: counts + item titles with attention_state
issues 42 --include timeline,trace  → 1 call: detail + events + code provenance
```

### Flow 2 Optimized: "What happened with this feature?" — 1-2 round trips

```
search "feature" -n 5          → find entities
issues 42 --include timeline,related → everything in one call
```

### Flow 3 Optimized: "Why was this code changed?" — 1 round trip

```
trace src/file.rs --include experts,timeline → full chain + experts + events
```

### Flow 4 Optimized: "Is the system healthy?" — 1 round trip

```
doctor                         → covers health + auth + connectivity
# status + stats only if doctor reveals issues
```

### Flow 6 Optimized: "Find and understand" — 2 round trips

```
search "query" -n 5            → discover entities
issues --batch 42,55,71 --include timeline → batch detail with events
```
