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
198
docs/command-surface-analysis/07-consolidation-proposals.md
Normal file
198
docs/command-surface-analysis/07-consolidation-proposals.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# Consolidation Proposals
|
||||
|
||||
5 proposals to reduce 34 commands to 29 by merging high-overlap commands.
|
||||
|
||||
---
|
||||
|
||||
## A. Absorb `file-history` into `trace --shallow`
|
||||
|
||||
**Overlap:** 75%. Both do rename chain BFS on `mr_file_changes`, both optionally include DiffNote discussions. `trace` follows `entity_references` to linked issues; `file-history` stops at MRs.
|
||||
|
||||
**Current state:**
|
||||
```bash
|
||||
# These do nearly the same thing:
|
||||
lore file-history src/auth/ -p proj --discussions
|
||||
lore trace src/auth/ -p proj --discussions
|
||||
# trace just adds: issues linked via entity_references
|
||||
```
|
||||
|
||||
**Proposed change:**
|
||||
- `trace <path>` — full chain: file -> MR -> issue -> discussions (existing behavior)
|
||||
- `trace <path> --shallow` — MR-only, no issue following (replaces `file-history`)
|
||||
- Move `--merged` flag from `file-history` to `trace`
|
||||
- Deprecate `file-history` as an alias that maps to `trace --shallow`
|
||||
|
||||
**Migration path:**
|
||||
1. Add `--shallow` and `--merged` flags to `trace`
|
||||
2. Make `file-history` an alias with deprecation warning
|
||||
3. Update robot-docs to point to `trace`
|
||||
4. Remove alias after 2 releases
|
||||
|
||||
**Breaking changes:** Robot output shape differs slightly (`trace_chains` vs `merge_requests` key name). The `--shallow` variant should match `file-history`'s output shape for compatibility.
|
||||
|
||||
**Effort:** Low. Most code is already shared via `resolve_rename_chain()`.
|
||||
|
||||
---
|
||||
|
||||
## B. Absorb `auth` into `doctor`
|
||||
|
||||
**Overlap:** 100% of `auth` is contained within `doctor`.
|
||||
|
||||
**Current state:**
|
||||
```bash
|
||||
lore auth # checks: token set, GitLab reachable, user identity
|
||||
lore doctor # checks: all of above + DB + schema + Ollama
|
||||
```
|
||||
|
||||
**Proposed change:**
|
||||
- `doctor` — full check (existing behavior)
|
||||
- `doctor --auth` — token + GitLab only (replaces `auth`)
|
||||
- Keep `health` separate (fast pre-flight, different exit code contract: 0/19)
|
||||
- Deprecate `auth` as alias for `doctor --auth`
|
||||
|
||||
**Migration path:**
|
||||
1. Add `--auth` flag to `doctor`
|
||||
2. Make `auth` an alias with deprecation warning
|
||||
3. Remove alias after 2 releases
|
||||
|
||||
**Breaking changes:** None for robot mode (same JSON shape). Exit code mapping needs verification.
|
||||
|
||||
**Effort:** Low. Doctor already has the auth check logic.
|
||||
|
||||
---
|
||||
|
||||
## C. Remove `related` query-mode
|
||||
|
||||
**Overlap:** 80% with `search --mode semantic`.
|
||||
|
||||
**Current state:**
|
||||
```bash
|
||||
# These are functionally equivalent:
|
||||
lore related "authentication flow"
|
||||
lore search "authentication flow" --mode semantic
|
||||
|
||||
# This is UNIQUE (no overlap):
|
||||
lore related issues 42
|
||||
```
|
||||
|
||||
**Proposed change:**
|
||||
- Keep entity-seeded mode: `related issues 42` (seeds from existing entity embedding)
|
||||
- Remove free-text mode: `related "text"` -> error with suggestion: "Use `search --mode semantic`"
|
||||
- Alternatively: keep as sugar but document it as equivalent to search
|
||||
|
||||
**Migration path:**
|
||||
1. Add deprecation warning when query-mode is used
|
||||
2. After 2 releases, remove query-mode parsing
|
||||
3. Entity-mode stays unchanged
|
||||
|
||||
**Breaking changes:** Agents using `related "text"` must switch to `search --mode semantic`. This is a strict improvement since search has filters.
|
||||
|
||||
**Effort:** Low. Just argument validation change.
|
||||
|
||||
---
|
||||
|
||||
## D. Merge `who overlap` into `who expert`
|
||||
|
||||
**Overlap:** 50% functional, but overlap is a strict simplification of expert.
|
||||
|
||||
**Current state:**
|
||||
```bash
|
||||
lore who src/auth/ # expert mode: scored rankings
|
||||
lore who --overlap src/auth/ # overlap mode: raw touch counts
|
||||
```
|
||||
|
||||
**Proposed change:**
|
||||
- `who <path>` (expert) adds `touch_count` and `last_touch_at` fields to each expert row
|
||||
- `who --overlap <path>` becomes an alias for `who <path> --fields username,touch_count`
|
||||
- Eventually remove `--overlap` flag
|
||||
|
||||
**New expert output:**
|
||||
```json
|
||||
{
|
||||
"experts": [
|
||||
{
|
||||
"username": "jdoe", "score": 42.5,
|
||||
"touch_count": 15, "last_touch_at": "2026-02-20",
|
||||
"detail": { "mr_ids_author": [99, 101] }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Migration path:**
|
||||
1. Add `touch_count` and `last_touch_at` to expert output
|
||||
2. Make `--overlap` an alias with deprecation warning
|
||||
3. Remove `--overlap` after 2 releases
|
||||
|
||||
**Breaking changes:** Expert output gains new fields (non-breaking for JSON consumers). Overlap output shape changes if agents were parsing `{ "users": [...] }` vs `{ "experts": [...] }`.
|
||||
|
||||
**Effort:** Low. Expert query already touches the same tables; just need to add a COUNT aggregation.
|
||||
|
||||
---
|
||||
|
||||
## E. Merge `count` and `status` into `stats`
|
||||
|
||||
**Overlap:** `count` and `stats` both answer "how much data?"; `status` and `stats` both report system state.
|
||||
|
||||
**Current state:**
|
||||
```bash
|
||||
lore count issues # entity count + state breakdown
|
||||
lore count mrs # entity count + state breakdown
|
||||
lore status # sync cursors per project
|
||||
lore stats # document/index counts + integrity
|
||||
```
|
||||
|
||||
**Proposed change:**
|
||||
- `stats` — document/index health (existing behavior, default)
|
||||
- `stats --entities` — adds entity counts (replaces `count`)
|
||||
- `stats --sync` — adds sync cursor positions (replaces `status`)
|
||||
- `stats --all` — everything: entities + sync + documents + integrity
|
||||
- `stats --check` / `--repair` — unchanged
|
||||
|
||||
**New `--all` output:**
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"entities": {
|
||||
"issues": { "total": 5000, "opened": 200, "closed": 4800 },
|
||||
"merge_requests": { "total": 1234, "opened": 100, "closed": 50, "merged": 1084 },
|
||||
"discussions": { "total": 8000 },
|
||||
"notes": { "total": 282000, "system_excluded": 50000 }
|
||||
},
|
||||
"sync": {
|
||||
"projects": [
|
||||
{ "project_path": "group/repo", "last_synced_at": "...", "document_count": 5000 }
|
||||
]
|
||||
},
|
||||
"documents": { "total": 61652, "issues": 5000, "mrs": 2000, "notes": 50000 },
|
||||
"embeddings": { "total": 80000, "synced": 79500, "pending": 500 },
|
||||
"fts": { "total_docs": 61652 },
|
||||
"queues": { "pending": 0, "in_progress": 0, "failed": 0 },
|
||||
"integrity": { "ok": true }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Migration path:**
|
||||
1. Add `--entities`, `--sync`, `--all` flags to `stats`
|
||||
2. Make `count` an alias for `stats --entities` with deprecation warning
|
||||
3. Make `status` an alias for `stats --sync` with deprecation warning
|
||||
4. Remove aliases after 2 releases
|
||||
|
||||
**Breaking changes:** `count` output currently has `{ "entity": "issues", "count": N, "breakdown": {...} }`. Under `stats --entities`, this becomes nested under `data.entities`. Alias can preserve old shape during deprecation period.
|
||||
|
||||
**Effort:** Medium. Need to compose three query paths into one response builder.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Consolidation | Removes | Effort | Breaking? |
|
||||
|---|---|---|---|
|
||||
| `file-history` -> `trace --shallow` | -1 command | Low | Alias redirect, output shape compat |
|
||||
| `auth` -> `doctor --auth` | -1 command | Low | Alias redirect |
|
||||
| `related` query-mode removal | -1 mode | Low | Must switch to `search --mode semantic` |
|
||||
| `who overlap` -> `who expert` | -1 sub-mode | Low | Output gains fields |
|
||||
| `count` + `status` -> `stats` | -2 commands | Medium | Output nesting changes |
|
||||
|
||||
**Total: 34 commands -> 29 commands.** All changes use deprecation-with-alias pattern for gradual migration.
|
||||
Reference in New Issue
Block a user