docs: add comprehensive command surface analysis
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>
This commit is contained in:
teernisse
170
docs/command-surface-analysis/05-overlap-analysis.md
Normal file
170
docs/command-surface-analysis/05-overlap-analysis.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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%
|
||||
Reference in New Issue
Block a user