gitlore/docs/command-surface-analysis/00-overview.md

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	issues, mrs, notes, search, count — flags, DB tables, robot schemas	Need command reference for entity queries
02-intelligence-commands.md	who, timeline, me, file-history, trace, related, drift	Need command reference for intelligence/analysis
03-pipeline-and-infra.md	sync, ingest, generate-docs, embed, diagnostics, setup	Need command reference for data management
04-data-flow.md	Shared data source map, command network graph, clusters	Understanding how commands interconnect
05-overlap-analysis.md	Quantified overlap percentages for every command pair	Evaluating what to consolidate
06-agent-workflows.md	Common agent flows, round-trip costs, token profiles	Understanding inefficiency pain points
07-consolidation-proposals.md	5 proposals to reduce 34 commands to 29	Planning command surface changes
08-robot-optimization-proposals.md	6 proposals for --include, --batch, --depth, etc.	Planning robot-mode improvements
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