gitlore/docs/command-surface-analysis/02-intelligence-commands.md

# 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": "..." }
    ]
  }
}
```