3f38b3fda7
Deep analysis of the full `lore` CLI command surface (34 commands across 6 categories) covering command inventory, data flow, overlap analysis, and optimization proposals. Document structure: - Main consolidated doc: docs/command-surface-analysis.md (1251 lines) - Split sections in docs/command-surface-analysis/ for navigation: 00-overview.md - Summary, inventory, priorities 01-entity-commands.md - issues, mrs, notes, search, count 02-intelligence-commands.md - who, timeline, me, file-history, trace, related, drift 03-pipeline-and-infra.md - sync, ingest, generate-docs, embed, diagnostics 04-data-flow.md - Shared data source map, command network graph 05-overlap-analysis.md - Quantified overlap percentages for every command pair 06-agent-workflows.md - Common agent flows, round-trip costs, token profiles 07-consolidation-proposals.md - 5 proposals to reduce 34 commands to 29 08-robot-optimization-proposals.md - 6 proposals for --include, --batch, --depth 09-appendices.md - Robot output envelope, field presets, exit codes Key findings: - High overlap pairs: who-workload/me (~85%), health/doctor (~90%) - 5 consolidation proposals to reduce command count by 15% - 6 robot-mode optimization proposals targeting agent round-trip reduction - Full DB table mapping and data flow documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
171 lines
8.4 KiB
Markdown
171 lines
8.4 KiB
Markdown
# 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%
|