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)

{
  "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)

{
  "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)

{
  "data": {
    "mode": "reviews",
    "result": {
      "categories": [
        {
          "category": "approval_rate",
          "reviewers": [{ "name": "jdoe", "count": 15, "percentage": 85.0 }]
        }
      ]
    }
  }
}

Robot Output (active)

{
  "data": {
    "mode": "active",
    "result": {
      "discussions": [
        { "entity_type": "mr", "iid": 99, "title": "Refactor auth", "participants": ["jdoe", "reviewer"] }
      ]
    }
  }
}

Robot Output (overlap)

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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)

{
  "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

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