# Overlap Analysis

Quantified functional duplication between commands.

---

## 1. High Overlap (>70%)

### `who workload` vs `me` — 85% overlap

| Dimension | `who @user` (workload) | `me --user @user` |
|---|---|---|
| Assigned issues | Yes | Yes |
| Authored MRs | Yes | Yes |
| Reviewing MRs | Yes | Yes |
| Attention state | No | **Yes** |
| Activity feed | No | **Yes** |
| Since-last-check inbox | No | **Yes** |
| Cross-project | Yes | **Yes** |

**Verdict:** `who workload` is a strict subset of `me`. The only reason to use `who workload` is if you DON'T want attention_state/activity/inbox — but `me --issues --mrs --fields minimal` achieves the same thing.

### `health` vs `doctor` — 90% overlap

| Check | `health` | `doctor` |
|---|---|---|
| Config found | Yes | Yes |
| DB exists | Yes | Yes |
| Schema current | Yes | Yes |
| Token valid | No | **Yes** |
| GitLab reachable | No | **Yes** |
| Ollama available | No | **Yes** |

**Verdict:** `health` is a strict subset of `doctor`. However, `health` has unique value as a ~50ms pre-flight with clean exit 0/19 semantics for scripting.

### `file-history` vs `trace` — 75% overlap

| Feature | `file-history` | `trace` |
|---|---|---|
| Find MRs for file | Yes | Yes |
| Rename chain BFS | Yes | Yes |
| DiffNote discussions | `--discussions` | `--discussions` |
| Follow to linked issues | No | **Yes** |
| `--merged` filter | **Yes** | No |

**Verdict:** `trace` is a superset of `file-history` minus the `--merged` filter. Both use the same `resolve_rename_chain()` function and query `mr_file_changes`.

### `related` query-mode vs `search --mode semantic` — 80% overlap

| Feature | `related "text"` | `search "text" --mode semantic` |
|---|---|---|
| Vector similarity | Yes | Yes |
| FTS component | No | No (semantic mode skips FTS) |
| Filters (labels, author, since) | No | **Yes** |
| Explain ranking | No | **Yes** |
| Field selection | No | **Yes** |
| Requires Ollama | Yes | Yes |

**Verdict:** `related "text"` is `search --mode semantic` without any filter capabilities. The entity-seeded mode (`related issues 42`) is NOT duplicated — it seeds from an existing entity's embedding.

---

## 2. Medium Overlap (40-70%)

### `who expert` vs `who overlap` — 50%

Both answer "who works on this file" but with different scoring:

| Aspect | `who expert` | `who overlap` |
|---|---|---|
| Scoring | Half-life decay, signal types (diffnote_author, reviewer, etc.) | Raw touch count |
| Output | Ranked experts with scores | Users with touch counts |
| Use case | "Who should review this?" | "Who else touches this?" |

**Verdict:** Overlap is a simplified version of expert. Expert could include touch_count as a field.

### `timeline` vs `trace` — 45%

Both follow `entity_references` to discover connected entities, but from different entry points:

| Aspect | `timeline` | `trace` |
|---|---|---|
| Entry point | Entity (issue/MR) or search query | File path |
| Direction | Entity -> cross-refs -> events | File -> MRs -> issues -> discussions |
| Output | Chronological events | Causal chains (why code changed) |
| Expansion | Depth-controlled cross-ref following | MR -> issue via entity_references |

**Verdict:** Complementary, not duplicative. Different questions, shared plumbing.

### `auth` vs `doctor` — 100% of auth

`auth` checks: token set + GitLab reachable + user identity.
`doctor` checks: all of the above + DB + schema + Ollama.

**Verdict:** `auth` is completely contained within `doctor`.

### `count` vs `stats` — 40%

Both answer "how much data?":

| Aspect | `count` | `stats` |
|---|---|---|
| Layer | Entity (issues, MRs, notes) | Document index |
| State breakdown | Yes (opened/closed/merged) | No |
| Integrity checks | No | Yes |
| Queue status | No | Yes |

**Verdict:** Different layers. Could be unified under `stats --entities`.

### `notes` vs `issues/mrs detail` — 50%

Both return note content:

| Aspect | `notes` command | Detail view discussions |
|---|---|---|
| Independent filtering | **Yes** (author, path, resolution, contains, type) | No |
| Parent context | Minimal (parent_iid, parent_title) | **Full** (complete entity + all discussions) |
| Cross-entity queries | **Yes** (all notes matching criteria) | No (one entity only) |

**Verdict:** `notes` is for filtered queries across entities. Detail views are for complete context on one entity. Different use cases.

---

## 3. No Significant Overlap

| Command | Why It's Unique |
|---|---|
| `drift` | Only command doing semantic divergence detection |
| `timeline` | Only command doing multi-entity chronological reconstruction with expansion |
| `search` (hybrid) | Only command combining FTS + vector with RRF ranking |
| `me` (inbox) | Only command with cursor-based since-last-check tracking |
| `who expert` | Only command with half-life decay scoring by signal type |
| `who reviews` | Only command analyzing review patterns (approval rate, latency) |
| `who active` | Only command surfacing unresolved discussions needing attention |

---

## 4. Overlap Adjacency Matrix

Rows/columns are commands. Values are estimated functional overlap percentage.

```
              issues  mrs  notes  search  who-e  who-w  who-r  who-a  who-o  timeline  me  fh  trace  related  drift  count  status  stats  health  doctor
issues          -     30    50      20      5      40      0      5      0       15    40    0     10      10      0     20       0      10      0       0
mrs            30      -    50      20      5      40      0      5      0       15    40    5     10      10      0     20       0      10      0       0
notes          50     50     -      15     15       0      5     10      0       10     0    5      5       0      0      0       0       0      0       0
search         20     20    15       -      0       0      0      0      0       15     0    0      0      80      0      0       0       5      0       0
who-expert      5      5    15       0      -       0     10      0     50        0     0   10     10       0      0      0       0       0      0       0
who-workload   40     40     0       0      0       -      0      0      0        0    85    0      0       0      0      0       0       0      0       0
who-reviews     0      0     5       0     10       0      -      0      0        0     0    0      0       0      0      0       0       0      0       0
who-active      5      5    10       0      0       0      0      -      0        5     0    0      0       0      0      0       0       0      0       0
who-overlap     0      0     0       0     50       0      0      0      -        0     0   10      5       0      0      0       0       0      0       0
timeline       15     15    10      15      0       0      0      5      0        -     5    5     45       0      0      0       0       0      0       0
me             40     40     0       0      0      85      0      0      0        5     -    0      0       0      0      0       5       0      5       5
file-history    0      5     5       0     10       0      0      0     10        5     0    -     75       0      0      0       0       0      0       0
trace          10     10     5       0     10       0      0      0      5       45     0   75      -       0      0      0       0       0      0       0
related        10     10     0      80      0       0      0      0      0        0     0    0      0       -      0      0       0       0      0       0
drift           0      0     0       0      0       0      0      0      0        0     0    0      0       0      -      0       0       0      0       0
count          20     20     0       0      0       0      0      0      0        0     0    0      0       0      0      -       0      40      0       0
status          0      0     0       0      0       0      0      0      0        0     5    0      0       0      0      0       -      20     30      40
stats          10     10     0       5      0       0      0      0      0        0     0    0      0       0      0     40      20       -      0      15
health          0      0     0       0      0       0      0      0      0        0     5    0      0       0      0      0      30       0      -      90
doctor          0      0     0       0      0       0      0      0      0        0     5    0      0       0      0      0      40      15     90       -
```

**Highest overlap pairs (>= 75%):**
1. `health` / `doctor` — 90%
2. `who workload` / `me` — 85%
3. `related` query-mode / `search semantic` — 80%
4. `file-history` / `trace` — 75%
