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>
8.4 KiB
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%):
health/doctor— 90%who workload/me— 85%relatedquery-mode /search semantic— 80%file-history/trace— 75%