theirongolddev/gitlore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add comprehensive command surface analysis

Browse Source 
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
2026-02-27 07:31:36 -05:00
parent 439c20e713
commit 3f38b3fda7
11 changed files with 3604 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

308
docs/command-surface-analysis/01-entity-commands.md Normal file
View File

@@ -0,0 +1,308 @@
# Entity Query Commands
Reference for: `issues`, `mrs`, `notes`, `search`, `count`
---
## `issues` (alias: `issue`)
List or show issues from local database.
| Flag | Type | Default | Purpose |
|---|---|---|---|
| `[IID]` | positional | — | Omit to list, provide to show detail |
| `-n, --limit` | int | 50 | Max results |
| `--fields` | string | — | Select output columns (preset: `minimal`) |
| `-s, --state` | enum | — | `opened\|closed\|all` |
| `-p, --project` | string | — | Filter by project (fuzzy) |
| `-a, --author` | string | — | Filter by author username |
| `-A, --assignee` | string | — | Filter by assignee username |
| `-l, --label` | string[] | — | Filter by labels (AND logic, repeatable) |
| `-m, --milestone` | string | — | Filter by milestone title |
| `--status` | string[] | — | Filter by work-item status (COLLATE NOCASE, OR logic) |
| `--since` | duration/date | — | Filter by created date (`7d`, `2w`, `YYYY-MM-DD`) |
| `--due-before` | date | — | Filter by due date |
| `--has-due` | flag | — | Show only issues with due dates |
| `--sort` | enum | `updated` | `updated\|created\|iid` |
| `--asc` | flag | — | Sort ascending |
| `-o, --open` | flag | — | Open first match in browser |
**DB tables:** `issues`, `projects`, `issue_assignees`, `issue_labels`, `labels`
**Detail mode adds:** `discussions`, `notes`, `entity_references` (closing MRs)
### Robot Output (list mode)
```json
{
"ok": true,
"data": {
"issues": [
{
"iid": 42, "title": "Fix auth", "state": "opened",
"author_username": "jdoe", "labels": ["backend"],
"assignees": ["jdoe"], "discussion_count": 3,
"unresolved_count": 1, "created_at_iso": "...",
"updated_at_iso": "...", "web_url": "...",
"project_path": "group/repo",
"status_name": "In progress"
}
],
"total_count": 150, "showing": 50
},
"meta": { "elapsed_ms": 40, "available_statuses": ["Open", "In progress", "Closed"] }
}
```
### Robot Output (detail mode — `issues <IID>`)
```json
{
"ok": true,
"data": {
"id": 12345, "iid": 42, "title": "Fix auth",
"description": "Full markdown body...",
"state": "opened", "author_username": "jdoe",
"created_at": "...", "updated_at": "...", "closed_at": null,
"confidential": false, "web_url": "...", "project_path": "group/repo",
"references_full": "group/repo#42",
"labels": ["backend"], "assignees": ["jdoe"],
"due_date": null, "milestone": null,
"user_notes_count": 5, "merge_requests_count": 1,
"closing_merge_requests": [
{ "iid": 99, "title": "Refactor auth", "state": "merged", "web_url": "..." }
],
"discussions": [
{
"notes": [
{ "author_username": "jdoe", "body": "...", "created_at": "...", "is_system": false }
],
"individual_note": false
}
],
"status_name": "In progress", "status_color": "#1068bf"
}
}
```
**Minimal preset:** `iid`, `title`, `state`, `updated_at_iso`
---
## `mrs` (aliases: `mr`, `merge-request`, `merge-requests`)
List or show merge requests.
| Flag | Type | Default | Purpose |
|---|---|---|---|
| `[IID]` | positional | — | Omit to list, provide to show detail |
| `-n, --limit` | int | 50 | Max results |
| `--fields` | string | — | Select output columns (preset: `minimal`) |
| `-s, --state` | enum | — | `opened\|merged\|closed\|locked\|all` |
| `-p, --project` | string | — | Filter by project |
| `-a, --author` | string | — | Filter by author |
| `-A, --assignee` | string | — | Filter by assignee |
| `-r, --reviewer` | string | — | Filter by reviewer |
| `-l, --label` | string[] | — | Filter by labels (AND) |
| `--since` | duration/date | — | Filter by created date |
| `-d, --draft` | flag | — | Draft MRs only |
| `-D, --no-draft` | flag | — | Exclude drafts |
| `--target` | string | — | Filter by target branch |
| `--source` | string | — | Filter by source branch |
| `--sort` | enum | `updated` | `updated\|created\|iid` |
| `--asc` | flag | — | Sort ascending |
| `-o, --open` | flag | — | Open in browser |
**DB tables:** `merge_requests`, `projects`, `mr_reviewers`, `mr_labels`, `labels`, `mr_assignees`
**Detail mode adds:** `discussions`, `notes`, `mr_diffs`
### Robot Output (list mode)
```json
{
"ok": true,
"data": {
"mrs": [
{
"iid": 99, "title": "Refactor auth", "state": "merged",
"draft": false, "author_username": "jdoe",
"source_branch": "feat/auth", "target_branch": "main",
"labels": ["backend"], "assignees": ["jdoe"], "reviewers": ["reviewer"],
"discussion_count": 5, "unresolved_count": 0,
"created_at_iso": "...", "updated_at_iso": "...",
"web_url": "...", "project_path": "group/repo"
}
],
"total_count": 500, "showing": 50
}
}
```
### Robot Output (detail mode — `mrs <IID>`)
```json
{
"ok": true,
"data": {
"id": 67890, "iid": 99, "title": "Refactor auth",
"description": "Full markdown body...",
"state": "merged", "draft": false, "author_username": "jdoe",
"source_branch": "feat/auth", "target_branch": "main",
"created_at": "...", "updated_at": "...",
"merged_at": "...", "closed_at": null,
"web_url": "...", "project_path": "group/repo",
"labels": ["backend"], "assignees": ["jdoe"], "reviewers": ["reviewer"],
"discussions": [
{
"notes": [
{
"author_username": "reviewer", "body": "...",
"created_at": "...", "is_system": false,
"position": { "new_path": "src/auth.rs", "new_line": 42 }
}
],
"individual_note": false
}
]
}
}
```
**Minimal preset:** `iid`, `title`, `state`, `updated_at_iso`
---
## `notes` (alias: `note`)
List discussion notes/comments with fine-grained filters.
| Flag | Type | Default | Purpose |
|---|---|---|---|
| `-n, --limit` | int | 50 | Max results |
| `--fields` | string | — | Preset: `minimal` |
| `-a, --author` | string | — | Filter by author |
| `--note-type` | enum | — | `DiffNote\|DiscussionNote` |
| `--contains` | string | — | Body text substring filter |
| `--note-id` | int | — | Internal note ID |
| `--gitlab-note-id` | int | — | GitLab note ID |
| `--discussion-id` | string | — | Discussion ID filter |
| `--include-system` | flag | — | Include system notes |
| `--for-issue` | int | — | Notes on specific issue (requires `-p`) |
| `--for-mr` | int | — | Notes on specific MR (requires `-p`) |
| `-p, --project` | string | — | Scope to project |
| `--since` | duration/date | — | Created after |
| `--until` | date | — | Created before (inclusive) |
| `--path` | string | — | File path filter (exact or prefix with `/`) |
| `--resolution` | enum | — | `any\|unresolved\|resolved` |
| `--sort` | enum | `created` | `created\|updated` |
| `--asc` | flag | — | Sort ascending |
| `--open` | flag | — | Open in browser |
**DB tables:** `notes`, `discussions`, `projects`, `issues`, `merge_requests`
### Robot Output
```json
{
"ok": true,
"data": {
"notes": [
{
"id": 1234, "gitlab_id": 56789,
"author_username": "reviewer", "body": "...",
"note_type": "DiffNote", "is_system": false,
"created_at_iso": "...", "updated_at_iso": "...",
"position_new_path": "src/auth.rs", "position_new_line": 42,
"resolvable": true, "resolved": false,
"noteable_type": "MergeRequest", "parent_iid": 99,
"parent_title": "Refactor auth", "project_path": "group/repo"
}
],
"total_count": 1000, "showing": 50
}
}
```
**Minimal preset:** `id`, `author_username`, `body`, `created_at_iso`
---
## `search` (aliases: `find`, `query`)
Semantic + full-text search across indexed documents.
| Flag | Type | Default | Purpose |
|---|---|---|---|
| `<QUERY>` | positional | required | Search query string |
| `--mode` | enum | `hybrid` | `lexical\|hybrid\|semantic` |
| `--type` | enum | — | `issue\|mr\|discussion\|note` |
| `--author` | string | — | Filter by author |
| `-p, --project` | string | — | Scope to project |
| `--label` | string[] | — | Filter by labels (AND) |
| `--path` | string | — | File path filter |
| `--since` | duration/date | — | Created after |
| `--updated-since` | duration/date | — | Updated after |
| `-n, --limit` | int | 20 | Max results (max: 100) |
| `--fields` | string | — | Preset: `minimal` |
| `--explain` | flag | — | Show ranking breakdown |
| `--fts-mode` | enum | `safe` | `safe\|raw` |
**DB tables:** `documents`, `documents_fts` (FTS5), `embeddings` (vec0), `document_labels`, `document_paths`, `projects`
**Search modes:**
- **lexical** — FTS5 with BM25 ranking (fastest, no Ollama needed)
- **hybrid** — RRF combination of lexical + semantic (default)
- **semantic** — Vector similarity only (requires Ollama)
### Robot Output
```json
{
"ok": true,
"data": {
"query": "authentication bug",
"mode": "hybrid",
"total_results": 15,
"results": [
{
"document_id": 1234, "source_type": "issue",
"title": "Fix SSO auth", "url": "...",
"author": "jdoe", "project_path": "group/repo",
"labels": ["auth"], "paths": ["src/auth/"],
"snippet": "...matching text...",
"score": 0.85,
"explain": { "vector_rank": 2, "fts_rank": 1, "rrf_score": 0.85 }
}
],
"warnings": []
}
}
```
**Minimal preset:** `document_id`, `title`, `source_type`, `score`
---
## `count`
Count entities in local database.
| Flag | Type | Default | Purpose |
|---|---|---|---|
| `<ENTITY>` | positional | required | `issues\|mrs\|discussions\|notes\|events\|references` |
| `-f, --for` | enum | — | Parent type: `issue\|mr` |
**DB tables:** Conditional aggregation on entity tables
### Robot Output
```json
{
"ok": true,
"data": {
"entity": "merge_requests",
"count": 1234,
"system_excluded": 5000,
"breakdown": { "opened": 100, "closed": 50, "merged": 1084 }
}
}
```