# Lore Command Surface Analysis — Overview

**Date:** 2026-02-26
**Version:** v0.9.1 (439c20e)

---

## Purpose

Deep analysis of the full `lore` CLI command surface: what each command does, how commands overlap, how they connect in agent workflows, and where consolidation and robot-mode optimization can reduce round trips and token waste.

## Document Map

| File | Contents | When to Read |
|---|---|---|
| **00-overview.md** | This file. Summary, inventory, priorities. | Always read first. |
| [01-entity-commands.md](01-entity-commands.md) | `issues`, `mrs`, `notes`, `search`, `count` — flags, DB tables, robot schemas | Need command reference for entity queries |
| [02-intelligence-commands.md](02-intelligence-commands.md) | `who`, `timeline`, `me`, `file-history`, `trace`, `related`, `drift` | Need command reference for intelligence/analysis |
| [03-pipeline-and-infra.md](03-pipeline-and-infra.md) | `sync`, `ingest`, `generate-docs`, `embed`, diagnostics, setup | Need command reference for data management |
| [04-data-flow.md](04-data-flow.md) | Shared data source map, command network graph, clusters | Understanding how commands interconnect |
| [05-overlap-analysis.md](05-overlap-analysis.md) | Quantified overlap percentages for every command pair | Evaluating what to consolidate |
| [06-agent-workflows.md](06-agent-workflows.md) | Common agent flows, round-trip costs, token profiles | Understanding inefficiency pain points |
| [07-consolidation-proposals.md](07-consolidation-proposals.md) | 5 proposals to reduce 34 commands to 29 | Planning command surface changes |
| [08-robot-optimization-proposals.md](08-robot-optimization-proposals.md) | 6 proposals for `--include`, `--batch`, `--depth`, etc. | Planning robot-mode improvements |
| [09-appendices.md](09-appendices.md) | Robot output envelope, field presets, exit codes | Reference material |

---

## Command Inventory (34 commands)

| Category | Commands | Count |
|---|---|---|
| Entity Query | `issues`, `mrs`, `notes`, `search`, `count` | 5 |
| Intelligence | `who` (5 modes), `timeline`, `related`, `drift`, `me`, `file-history`, `trace` | 7 (11 with who sub-modes) |
| Data Pipeline | `sync`, `ingest`, `generate-docs`, `embed` | 4 |
| Diagnostics | `health`, `auth`, `doctor`, `status`, `stats` | 5 |
| Setup | `init`, `token`, `cron`, `migrate` | 4 |
| Meta | `version`, `completions`, `robot-docs` | 3 |

---

## Key Findings

### High-Overlap Pairs

| Pair | Overlap | Recommendation |
|---|---|---|
| `who workload` vs `me` | ~85% | Workload is a strict subset of me |
| `health` vs `doctor` | ~90% | Health is a strict subset of doctor |
| `file-history` vs `trace` | ~75% | Trace is a superset minus `--merged` |
| `related` query-mode vs `search --mode semantic` | ~80% | Related query-mode is search without filters |
| `auth` vs `doctor` | ~100% of auth | Auth is fully contained within doctor |

### Agent Workflow Pain Points

| Workflow | Current Round Trips | With Optimizations |
|---|---|---|
| "Understand this issue" | 4 calls | 1 call (`--include`) |
| "Why was code changed?" | 3 calls | 1 call (`--include`) |
| "What should I work on?" | 4 calls | 2 calls |
| "Find and understand" | 4 calls | 2 calls |
| "Is system healthy?" | 2-4 calls | 1 call |

---

## Priority Ranking

| Pri | Proposal | Category | Effort | Impact |
|---|---|---|---|---|
| **P0** | `--include` flag on detail commands | Robot optimization | High | Eliminates 2-3 round trips per workflow |
| **P0** | `--depth` on `me` command | Robot optimization | Low | 60-80% token reduction on most-used command |
| **P1** | `--batch` for detail views | Robot optimization | Medium | Eliminates N+1 after search/timeline |
| **P1** | Absorb `file-history` into `trace` | Consolidation | Low | Cleaner surface, shared code |
| **P1** | Merge `who overlap` into `who expert` | Consolidation | Low | -1 round trip in review flows |
| **P2** | `context` composite command | Robot optimization | Medium | Single entry point for entity understanding |
| **P2** | Merge `count`+`status` into `stats` | Consolidation | Medium | -2 commands, progressive disclosure |
| **P2** | Absorb `auth` into `doctor` | Consolidation | Low | -1 command |
| **P2** | Remove `related` query-mode | Consolidation | Low | -1 confusing choice |
| **P3** | `--max-tokens` budget | Robot optimization | High | Flexible but complex to implement |
| **P3** | `--format tsv` | Robot optimization | Medium | High savings, limited applicability |

### Consolidation Summary

| Before | After | Removed |
|---|---|---|
| `file-history` + `trace` | `trace` (+ `--shallow`) | -1 |
| `auth` + `doctor` | `doctor` (+ `--auth`) | -1 |
| `related` query-mode | `search --mode semantic` | -1 mode |
| `who overlap` + `who expert` | `who expert` (+ touch_count) | -1 sub-mode |
| `count` + `status` + `stats` | `stats` (+ `--entities`, `--sync`) | -2 |

**Total: 34 commands -> 29 commands**