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
452
docs/command-surface-analysis/02-intelligence-commands.md
Normal file
452
docs/command-surface-analysis/02-intelligence-commands.md
Normal file
@@ -0,0 +1,452 @@
|
||||
# Intelligence Commands
|
||||
|
||||
Reference for: `who`, `timeline`, `me`, `file-history`, `trace`, `related`, `drift`
|
||||
|
||||
---
|
||||
|
||||
## `who` (People Intelligence)
|
||||
|
||||
Five sub-modes, dispatched by argument shape.
|
||||
|
||||
| Mode | Trigger | Purpose |
|
||||
|---|---|---|
|
||||
| **expert** | `who <path>` or `who --path <path>` | Who knows about a code area? |
|
||||
| **workload** | `who @username` | What is this person working on? |
|
||||
| **reviews** | `who @username --reviews` | Review pattern analysis |
|
||||
| **active** | `who --active` | Unresolved discussions needing attention |
|
||||
| **overlap** | `who --overlap <path>` | Who else touches these files? |
|
||||
|
||||
### Shared Flags
|
||||
|
||||
| Flag | Type | Default | Purpose |
|
||||
|---|---|---|---|
|
||||
| `-p, --project` | string | — | Scope to project |
|
||||
| `-n, --limit` | int | varies | Max results (1-500) |
|
||||
| `--fields` | string | — | Preset: `minimal` |
|
||||
| `--since` | duration/date | — | Time window |
|
||||
| `--include-bots` | flag | — | Include bot users |
|
||||
| `--include-closed` | flag | — | Include closed issues/MRs |
|
||||
| `--all-history` | flag | — | Query all history |
|
||||
|
||||
### Expert-Only Flags
|
||||
|
||||
| Flag | Type | Default | Purpose |
|
||||
|---|---|---|---|
|
||||
| `--detail` | flag | — | Per-MR breakdown |
|
||||
| `--as-of` | date/duration | — | Score at point in time |
|
||||
| `--explain-score` | flag | — | Score breakdown |
|
||||
|
||||
### DB Tables by Mode
|
||||
|
||||
| Mode | Primary Tables |
|
||||
|---|---|
|
||||
| expert | `notes` (INDEXED BY idx_notes_diffnote_path_created), `merge_requests`, `mr_reviewers` |
|
||||
| workload | `issues`, `merge_requests`, `mr_reviewers` |
|
||||
| reviews | `merge_requests`, `discussions`, `notes` |
|
||||
| active | `discussions`, `notes`, `issues`, `merge_requests` |
|
||||
| overlap | `notes`, `mr_file_changes`, `merge_requests` |
|
||||
|
||||
### Robot Output (expert)
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"mode": "expert",
|
||||
"input": { "target": "src/auth/", "path": "src/auth/" },
|
||||
"resolved_input": { "mode": "expert", "project_id": 1, "project_path": "group/repo" },
|
||||
"result": {
|
||||
"experts": [
|
||||
{
|
||||
"username": "jdoe", "score": 42.5,
|
||||
"detail": { "mr_ids_author": [99, 101], "mr_ids_reviewer": [88] }
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Robot Output (workload)
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"mode": "workload",
|
||||
"result": {
|
||||
"assigned_issues": [{ "iid": 42, "title": "Fix auth", "state": "opened" }],
|
||||
"authored_mrs": [{ "iid": 99, "title": "Refactor auth", "state": "merged" }],
|
||||
"review_mrs": [{ "iid": 88, "title": "Add SSO", "state": "opened" }]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Robot Output (reviews)
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"mode": "reviews",
|
||||
"result": {
|
||||
"categories": [
|
||||
{
|
||||
"category": "approval_rate",
|
||||
"reviewers": [{ "name": "jdoe", "count": 15, "percentage": 85.0 }]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Robot Output (active)
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"mode": "active",
|
||||
"result": {
|
||||
"discussions": [
|
||||
{ "entity_type": "mr", "iid": 99, "title": "Refactor auth", "participants": ["jdoe", "reviewer"] }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Robot Output (overlap)
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"mode": "overlap",
|
||||
"result": {
|
||||
"users": [{ "username": "jdoe", "touch_count": 15 }]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Minimal Presets
|
||||
|
||||
| Mode | Fields |
|
||||
|---|---|
|
||||
| expert | `username`, `score` |
|
||||
| workload | `iid`, `title`, `state` |
|
||||
| reviews | `name`, `count`, `percentage` |
|
||||
| active | `entity_type`, `iid`, `title`, `participants` |
|
||||
| overlap | `username`, `touch_count` |
|
||||
|
||||
---
|
||||
|
||||
## `timeline`
|
||||
|
||||
Reconstruct chronological event history for a topic/entity with cross-reference expansion.
|
||||
|
||||
| Flag | Type | Default | Purpose |
|
||||
|---|---|---|---|
|
||||
| `<QUERY>` | positional | required | Search text or entity ref (`issue:42`, `mr:99`) |
|
||||
| `-p, --project` | string | — | Scope to project |
|
||||
| `--since` | duration/date | — | Filter events after |
|
||||
| `--depth` | int | 1 | Cross-ref expansion depth (0=none) |
|
||||
| `--no-mentions` | flag | — | Skip "mentioned" edges, keep "closes"/"related" |
|
||||
| `-n, --limit` | int | 100 | Max events |
|
||||
| `--fields` | string | — | Preset: `minimal` |
|
||||
| `--max-seeds` | int | 10 | Max seed entities from search |
|
||||
| `--max-entities` | int | 50 | Max expanded entities |
|
||||
| `--max-evidence` | int | 10 | Max evidence notes |
|
||||
|
||||
**Pipeline:** SEED -> HYDRATE -> EXPAND -> COLLECT -> RENDER
|
||||
|
||||
**DB tables:** `issues`, `merge_requests`, `discussions`, `notes`, `entity_references`, `resource_state_events`, `resource_label_events`, `resource_milestone_events`, `documents` (for search seeding)
|
||||
|
||||
### Robot Output
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"query": "authentication", "event_count": 25,
|
||||
"seed_entities": [{ "type": "issue", "iid": 42, "project": "group/repo" }],
|
||||
"expanded_entities": [
|
||||
{
|
||||
"type": "mr", "iid": 99, "project": "group/repo", "depth": 1,
|
||||
"via": {
|
||||
"from": { "type": "issue", "iid": 42 },
|
||||
"reference_type": "closes"
|
||||
}
|
||||
}
|
||||
],
|
||||
"unresolved_references": [
|
||||
{
|
||||
"source": { "type": "issue", "iid": 42, "project": "group/repo" },
|
||||
"target_type": "mr", "target_iid": 200, "reference_type": "mentioned"
|
||||
}
|
||||
],
|
||||
"events": [
|
||||
{
|
||||
"timestamp": "2026-01-15T10:30:00Z",
|
||||
"entity_type": "issue", "entity_iid": 42, "project": "group/repo",
|
||||
"event_type": "state_changed", "summary": "Reopened",
|
||||
"actor": "jdoe", "is_seed": true,
|
||||
"evidence_notes": [{ "author": "jdoe", "snippet": "..." }]
|
||||
}
|
||||
]
|
||||
},
|
||||
"meta": {
|
||||
"elapsed_ms": 150, "search_mode": "fts",
|
||||
"expansion_depth": 1, "include_mentions": true,
|
||||
"total_entities": 5, "total_events": 25,
|
||||
"evidence_notes_included": 8, "discussion_threads_included": 3,
|
||||
"unresolved_references": 1, "showing": 25
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Minimal preset:** `timestamp`, `type`, `entity_iid`, `detail`
|
||||
|
||||
---
|
||||
|
||||
## `me` (Personal Dashboard)
|
||||
|
||||
Personal work dashboard with issues, MRs, activity, and since-last-check inbox.
|
||||
|
||||
| Flag | Type | Default | Purpose |
|
||||
|---|---|---|---|
|
||||
| `--issues` | flag | — | Open issues section only |
|
||||
| `--mrs` | flag | — | MRs section only |
|
||||
| `--activity` | flag | — | Activity feed only |
|
||||
| `--since` | duration/date | `30d` | Activity window |
|
||||
| `-p, --project` | string | — | Scope to one project |
|
||||
| `--all` | flag | — | All synced projects |
|
||||
| `--user` | string | — | Override configured username |
|
||||
| `--fields` | string | — | Preset: `minimal` |
|
||||
| `--reset-cursor` | flag | — | Clear since-last-check cursor |
|
||||
|
||||
**Sections (no flags = all):** Issues, MRs authored, MRs reviewing, Activity, Inbox
|
||||
|
||||
**DB tables:** `issues`, `merge_requests`, `resource_state_events`, `projects`, `issue_labels`, `mr_labels`
|
||||
|
||||
### Robot Output
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"username": "jdoe",
|
||||
"summary": {
|
||||
"project_count": 3, "open_issue_count": 5,
|
||||
"authored_mr_count": 2, "reviewing_mr_count": 1,
|
||||
"needs_attention_count": 3
|
||||
},
|
||||
"since_last_check": {
|
||||
"cursor_iso": "2026-02-25T18:00:00Z",
|
||||
"total_event_count": 8,
|
||||
"groups": [
|
||||
{
|
||||
"entity_type": "issue", "entity_iid": 42,
|
||||
"entity_title": "Fix auth", "project": "group/repo",
|
||||
"events": [
|
||||
{ "timestamp_iso": "...", "event_type": "comment",
|
||||
"actor": "reviewer", "summary": "New comment" }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"open_issues": [
|
||||
{
|
||||
"project": "group/repo", "iid": 42, "title": "Fix auth",
|
||||
"state": "opened", "attention_state": "needs_attention",
|
||||
"status_name": "In progress", "labels": ["auth"],
|
||||
"updated_at_iso": "..."
|
||||
}
|
||||
],
|
||||
"open_mrs_authored": [
|
||||
{
|
||||
"project": "group/repo", "iid": 99, "title": "Refactor auth",
|
||||
"state": "opened", "attention_state": "needs_attention",
|
||||
"draft": false, "labels": ["backend"], "updated_at_iso": "..."
|
||||
}
|
||||
],
|
||||
"reviewing_mrs": [],
|
||||
"activity": [
|
||||
{
|
||||
"timestamp_iso": "...", "event_type": "state_changed",
|
||||
"entity_type": "issue", "entity_iid": 42, "project": "group/repo",
|
||||
"actor": "jdoe", "is_own": true, "summary": "Closed"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Minimal presets:** Items: `iid, title, attention_state, updated_at_iso` | Activity: `timestamp_iso, event_type, entity_iid, actor`
|
||||
|
||||
---
|
||||
|
||||
## `file-history`
|
||||
|
||||
Show which MRs touched a file, with linked discussions.
|
||||
|
||||
| Flag | Type | Default | Purpose |
|
||||
|---|---|---|---|
|
||||
| `<PATH>` | positional | required | File path to trace |
|
||||
| `-p, --project` | string | — | Scope to project |
|
||||
| `--discussions` | flag | — | Include DiffNote snippets |
|
||||
| `--no-follow-renames` | flag | — | Skip rename chain resolution |
|
||||
| `--merged` | flag | — | Only merged MRs |
|
||||
| `-n, --limit` | int | 50 | Max MRs |
|
||||
|
||||
**DB tables:** `mr_file_changes`, `merge_requests`, `notes` (DiffNotes), `projects`
|
||||
|
||||
### Robot Output
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"path": "src/auth/middleware.rs",
|
||||
"rename_chain": [
|
||||
{ "previous_path": "src/auth.rs", "mr_iid": 55, "merged_at": "..." }
|
||||
],
|
||||
"merge_requests": [
|
||||
{
|
||||
"iid": 99, "title": "Refactor auth", "state": "merged",
|
||||
"author": "jdoe", "merged_at": "...", "change_type": "modified"
|
||||
}
|
||||
],
|
||||
"discussions": [
|
||||
{
|
||||
"discussion_id": 123, "mr_iid": 99, "author": "reviewer",
|
||||
"body_snippet": "...", "path": "src/auth/middleware.rs"
|
||||
}
|
||||
]
|
||||
},
|
||||
"meta": { "elapsed_ms": 30, "total_mrs": 5, "renames_followed": true }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `trace`
|
||||
|
||||
File -> MR -> issue -> discussion chain to understand why code was introduced.
|
||||
|
||||
| Flag | Type | Default | Purpose |
|
||||
|---|---|---|---|
|
||||
| `<PATH>` | positional | required | File path (future: `:line` suffix) |
|
||||
| `-p, --project` | string | — | Scope to project |
|
||||
| `--discussions` | flag | — | Include DiffNote snippets |
|
||||
| `--no-follow-renames` | flag | — | Skip rename chain |
|
||||
| `-n, --limit` | int | 20 | Max chains |
|
||||
|
||||
**DB tables:** `mr_file_changes`, `merge_requests`, `issues`, `discussions`, `notes`, `entity_references`
|
||||
|
||||
### Robot Output
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"path": "src/auth/middleware.rs",
|
||||
"resolved_paths": ["src/auth/middleware.rs", "src/auth.rs"],
|
||||
"trace_chains": [
|
||||
{
|
||||
"mr_iid": 99, "mr_title": "Refactor auth", "mr_state": "merged",
|
||||
"mr_author": "jdoe", "change_type": "modified",
|
||||
"merged_at_iso": "...", "web_url": "...",
|
||||
"issues": [42],
|
||||
"discussions": [
|
||||
{
|
||||
"discussion_id": 123, "author_username": "reviewer",
|
||||
"body_snippet": "...", "path": "src/auth/middleware.rs"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"meta": { "tier": "api_only", "total_chains": 3, "renames_followed": 1 }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `related`
|
||||
|
||||
Find semantically related entities via vector search.
|
||||
|
||||
| Flag | Type | Default | Purpose |
|
||||
|---|---|---|---|
|
||||
| `<QUERY_OR_TYPE>` | positional | required | Entity type (`issues`, `mrs`) or free text |
|
||||
| `[IID]` | positional | — | Entity IID (required with entity type) |
|
||||
| `-n, --limit` | int | 10 | Max results |
|
||||
| `-p, --project` | string | — | Scope to project |
|
||||
|
||||
**Two modes:**
|
||||
- **Entity mode:** `related issues 42` — find entities similar to issue #42
|
||||
- **Query mode:** `related "auth flow"` — find entities matching free text
|
||||
|
||||
**DB tables:** `documents`, `embeddings` (vec0), `projects`
|
||||
|
||||
**Requires:** Ollama running (for query mode embedding)
|
||||
|
||||
### Robot Output (entity mode)
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"query_entity_type": "issue",
|
||||
"query_entity_iid": 42,
|
||||
"query_entity_title": "Fix SSO authentication",
|
||||
"similar_entities": [
|
||||
{
|
||||
"entity_type": "mr", "entity_iid": 99,
|
||||
"entity_title": "Refactor auth module",
|
||||
"project_path": "group/repo", "state": "merged",
|
||||
"similarity_score": 0.87,
|
||||
"shared_labels": ["auth"], "shared_authors": ["jdoe"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `drift`
|
||||
|
||||
Detect discussion divergence from original intent.
|
||||
|
||||
| Flag | Type | Default | Purpose |
|
||||
|---|---|---|---|
|
||||
| `<ENTITY_TYPE>` | positional | required | Currently only `issues` |
|
||||
| `<IID>` | positional | required | Entity IID |
|
||||
| `--threshold` | f32 | 0.4 | Similarity threshold (0.0-1.0) |
|
||||
| `-p, --project` | string | — | Scope to project |
|
||||
|
||||
**DB tables:** `issues`, `discussions`, `notes`, `embeddings`
|
||||
|
||||
**Requires:** Ollama running
|
||||
|
||||
### Robot Output
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"entity_type": "issue", "entity_iid": 42,
|
||||
"total_notes": 15,
|
||||
"detected_drift": true,
|
||||
"drift_point": {
|
||||
"note_index": 8, "similarity": 0.32,
|
||||
"author": "someone", "created_at": "..."
|
||||
},
|
||||
"similarity_curve": [
|
||||
{ "note_index": 0, "similarity": 0.95, "author": "jdoe", "created_at": "..." },
|
||||
{ "note_index": 1, "similarity": 0.88, "author": "reviewer", "created_at": "..." }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user