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
92
docs/command-surface-analysis/00-overview.md
Normal file
92
docs/command-surface-analysis/00-overview.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# 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**
|
||||
Reference in New Issue
Block a user