# Lore CLI User Journeys

## Purpose

Map realistic workflows for both human users and AI agents to identify gaps in the command surface and optimization opportunities. Each journey starts with a **problem** and traces the commands needed to reach a **resolution**.

---

## Part 1: Human User Flows

### H1. Morning Standup Prep

**Problem:** "What happened since yesterday? I need to know what moved before standup."

**Flow:**
```
lore sync -q                              # Refresh data (quiet, no noise)
lore issues -s opened --since 1d          # Issues that changed overnight
lore mrs -s opened --since 1d             # MRs that moved
lore who @me                              # My current workload snapshot
```

**Gap identified:** No single "activity feed" command. User runs 3 queries to get what should be one view. No `--since 1d` shorthand for "since yesterday." No `@me` alias for the authenticated user.

---

### H2. Sprint Planning: What's Ready to Pick Up?

**Problem:** "We're planning the next sprint. What's open, unassigned, and actionable?"

**Flow:**
```
lore issues -s opened -p myproject        # All open issues
lore issues -s opened -l "ready"          # Issues labeled ready
lore issues -s opened --has-due           # Issues with deadlines approaching
lore count issues -p myproject            # How many total?
```

**Gap identified:** No way to filter by "unassigned" issues (missing `--no-assignee` flag). No way to sort by due date. No way to see priority/weight. Can't combine filters like "opened AND no assignee AND has due date."

---

### H3. Investigating a Production Incident

**Problem:** "Deploy broke prod. I need the full timeline of what changed around the deploy."

**Flow:**
```
lore sync -q                              # Get latest
lore timeline "deploy" --since 7d         # What happened around deploys
lore search "deploy" --type mr            # MRs mentioning deploy
lore mrs 456                              # Inspect the suspicious MR
lore who --overlap src/deploy/            # Who else touches deploy code
```

**Gap identified:** Timeline is keyword-based, not event-based. Can't filter by "MRs merged in the last 24 hours" directly. No way to see which MRs were merged between two dates (release diff). Would benefit from `lore mrs -s merged --since 1d`.

---

### H4. Preparing to Review Someone's MR

**Problem:** "I was assigned to review MR !789. I need context before diving in."

**Flow:**
```
lore mrs 789                              # Read the MR description + discussions
lore mrs 789 -o                           # Open in browser for the actual diff
lore who src/features/auth/               # Who are the experts in this area?
lore search "auth refactor" --type issue  # Related issues for background
lore timeline "authentication"            # History of auth changes
```

**Gap identified:** No way to see the file list touched by an MR from the CLI (data is stored in `mr_file_changes` but not surfaced). No way to link an MR back to its closing issue(s) from the MR detail view. The cross-reference data exists in `entity_references` but isn't shown in `mrs <iid>` output.

---

### H5. Onboarding to an Unfamiliar Code Area

**Problem:** "I'm new to the team and need to understand how the billing module works."

**Flow:**
```
lore search "billing" -n 20               # What exists about billing?
lore who src/billing/                      # Who knows billing best?
lore timeline "billing" --depth 2         # History of billing changes
lore mrs -s merged -l billing --since 6m  # Recent merged billing work
lore issues -s opened -l billing          # Outstanding billing issues
```

**Gap identified:** No way to get a "module overview" in one command. The search spans issues, MRs, and discussions but doesn't summarize by category. No way to see the most-discussed or most-referenced entities (high-signal items for understanding).

---

### H6. Finding the Right Reviewer for My PR

**Problem:** "I'm about to submit a PR touching auth and payments. Who should review?"

**Flow:**
```
lore who src/features/auth/               # Auth experts
lore who src/features/payments/           # Payment experts
lore who @candidate1                      # Check candidate1's workload
lore who @candidate2                      # Check candidate2's workload
```

**Gap identified:** No way to query multiple paths at once (`lore who src/auth/ src/payments/`). No way to find the intersection of expertise. No workload-aware recommendation ("who knows this AND has bandwidth"). Four separate commands for what should be one decision.

---

### H7. Understanding Why a Feature Was Built This Way

**Problem:** "This code is weird. Why was it implemented like this? What was the original discussion?"

**Flow:**
```
lore search "feature-name rationale"      # Search for decision context
lore timeline "feature-name" --depth 2    # Full history with cross-refs
lore issues 234                           # Read the original issue
lore mrs 567                              # Read the implementation MR
```

**Gap identified:** No way to search within a specific issue's or MR's discussion notes. The search covers documents (titles + descriptions) but per-note search isn't available yet (PRD exists). No way to navigate "issue 234 was closed by MR 567" without manually knowing both IDs.

---

### H8. Checking Team Workload Before Assigning Work

**Problem:** "I need to assign this urgent bug. Who has the least on their plate?"

**Flow:**
```
lore who @alice                           # Alice's workload
lore who @bob                             # Bob's workload
lore who @carol                           # Carol's workload
lore who @dave                            # Dave's workload
```

**Gap identified:** No team-level workload view. Must query each person individually. No way to list "all assignees and their open issue counts." No concept of a team roster. Would benefit from `lore who --team` or `lore workload`.

---

### H9. Preparing Release Notes

**Problem:** "We're cutting a release. I need to summarize what's in this version."

**Flow:**
```
lore mrs -s merged --since 2w -p myproject   # MRs merged since last release
lore issues -s closed --since 2w -p myproject # Issues closed since last release
lore mrs -s merged -l feature --since 2w      # Feature MRs specifically
lore mrs -s merged -l bugfix --since 2w       # Bugfix MRs
```

**Gap identified:** No way to filter by milestone (for version-based releases). Wait -- `issues` has `-m` for milestone but `mrs` does not. No changelog generation. No "what closed between tag A and tag B." No grouping by label for release note categories.

---

### H10. Finding and Closing Stale Issues

**Problem:** "Our backlog is bloated. Which issues haven't been touched in months?"

**Flow:**
```
lore issues -s opened --sort updated --asc -n 50  # Oldest-updated first
# Then manually inspect each one...
lore issues 42                                      # Is this still relevant?
```

**Gap identified:** No `--before` or `--updated-before` filter (only `--since` exists). Can sort ascending but can't filter "not updated in 90 days." No staleness indicator. No bulk operations concept.

---

### H11. Understanding a Bug's Full History

**Problem:** "Bug #321 keeps getting reopened. I need to understand its entire lifecycle."

**Flow:**
```
lore issues 321                           # Read the issue
lore timeline "bug-keyword" -p myproject  # Try to find timeline events
# But timeline is keyword-based, not entity-based...
```

**Gap identified:** No way to get a timeline for a specific entity by IID. `lore timeline` requires a keyword query, not an entity reference. Would benefit from `lore timeline --issue 321` or `lore timeline --mr 456` to get the event history of a specific entity directly.

---

### H12. Identifying Who to Ask About Failing Tests

**Problem:** "CI tests are failing in `src/lib/parser.rs`. Who last touched this?"

**Flow:**
```
lore who src/lib/parser.rs                # Expert lookup
lore who --overlap src/lib/parser.rs      # Who else has touched it
lore search "parser" --type mr --since 2w # Recent MRs touching parser
```

**Gap identified:** Expert mode uses DiffNote analysis (code review comments), not actual file change tracking. The `mr_file_changes` table has the real data but `who` doesn't use it for attribution. Could be much more accurate with file-change-based expertise.

---

### H13. Tracking a Feature Across Multiple MRs

**Problem:** "The 'dark mode' feature spans 5 MRs. I need to see them all together."

**Flow:**
```
lore mrs -l dark-mode                     # MRs with the label
lore issues -l dark-mode                  # Related issues
lore timeline "dark mode" --depth 2       # Cross-referenced events
```

**Gap identified:** Works reasonably well with labels as the grouping mechanism. But if the team didn't label consistently, there's no way to discover related MRs by content similarity. No "related items" view that combines issues + MRs + discussions for a topic.

---

### H14. Checking if a Similar Fix Was Already Attempted

**Problem:** "Before I implement this fix, was something similar tried before?"

**Flow:**
```
lore search "memory leak connection pool" # Semantic search
lore search "connection pool" --type mr -s all  # Wait, no state filter on search
lore mrs -s closed -l bugfix              # Closed bugfix MRs (coarse)
lore timeline "connection pool"           # Historical context
```

**Gap identified:** Search doesn't have a `--state` filter. Can't search only closed/merged items. The semantic search is powerful but can't be combined with entity state. Would benefit from `--state merged` on search to find past attempts.

---

### H15. Reviewing Discussions That Need My Attention

**Problem:** "Which discussion threads am I involved in that are still unresolved?"

**Flow:**
```
lore who --active                         # All active unresolved discussions
lore who --active --since 30d             # Wider window
# But can't filter to "discussions I'm in"...
```

**Gap identified:** `--active` shows all unresolved discussions, not filtered by participant. No way to say "show me discussions where @me participated." No notification/mention tracking. No "my unresolved threads" view.

---

## Part 2: AI Agent Flows

### A1. Context Gathering Before Code Modification

**Problem:** Agent is about to modify `src/features/auth/session.rs` and needs full context.

**Flow:**
```
lore -J health                            # Pre-flight check
lore -J who src/features/auth/            # Who knows this area
lore -J search "auth session" -n 10       # Related issues/MRs
lore -J mrs -s merged --since 3m -l auth  # Recent auth changes
lore -J who --overlap src/features/auth/session.rs  # Concurrent work risk
```

**Gap identified:** No way to check "are there open MRs touching this file right now?" The overlap mode shows historical touches, not active branches. An agent needs to know about in-flight changes to avoid conflicts.

---

### A2. Auto-Triaging an Incoming Issue

**Problem:** Agent receives a new issue and needs to categorize it, find related work, and suggest assignees.

**Flow:**
```
lore -J issues 999                        # Read the new issue
lore -J search "$(extract_keywords)" --explain  # Find similar past issues
lore -J who src/affected/path/            # Suggest experts as assignees
lore -J issues -s opened -l same-label    # Check for duplicates
```

**Gap identified:** No way to get just the description text for programmatic keyword extraction. `issues <iid>` returns full detail including discussions. Agent must parse the full response to extract the description for a secondary search. Would benefit from `--fields description` on detail view. No duplicate detection built in.

---

### A3. Generating Sprint Status Report

**Problem:** Agent needs to produce a weekly status report for the team.

**Flow:**
```
lore -J issues -s closed --since 1w --fields minimal  # Completed work
lore -J issues -s opened --status "In progress"        # In-flight work
lore -J mrs -s merged --since 1w --fields minimal      # Merged PRs
lore -J mrs -s opened -D --fields minimal              # Open non-draft MRs
lore -J count issues                                    # Totals
lore -J count mrs                                       # MR totals
lore -J who --active --since 1w                         # Discussions needing attention
```

**Gap identified:** Seven separate queries for one report. No `lore summary` or `lore report` command. No way to get "issues transitioned from X to Y this week" (state change history exists in events but isn't queryable). No velocity metric (issues closed per week trend).

---

### A4. Finding Relevant Prior Art Before Implementing

**Problem:** Agent is implementing a caching layer and wants to find if similar patterns exist in the codebase's GitLab history.

**Flow:**
```
lore -J search "caching" --mode hybrid -n 20 --explain
lore -J search "cache invalidation" --mode hybrid -n 10
lore -J search "redis" --mode lexical --type discussion   # Exact term in discussions
lore -J timeline "cache" --since 1y                        # Wait, max is 1y? Let's try 12m
```

**Gap identified:** No way to search discussion notes individually (per-note search). Discussions are aggregated into documents, so individual note-level matches are lost. The `--explain` flag helps but doesn't show which specific note matched. No `--since 1y` or `--since 12m` duration format.

---

### A5. Building Context for PR Description

**Problem:** Agent wrote code and needs to generate a PR description that references relevant issues.

**Flow:**
```
lore -J search "feature description keywords" --type issue
lore -J issues -s opened -l feature-label --fields iid,title,web_url
# Cross-reference: which issues does this MR close?
# No command for this -- must manually scan search results
```

**Gap identified:** No way to query the `entity_references` table directly. Agent can't ask "which issues reference MR !456" or "which issues contain 'closes #123' in their text." The data exists but isn't exposed as a query surface. Would benefit from `lore refs --mr 456` or `lore refs --issue 123`.

---

### A6. Identifying Affected Experts for Review Assignment

**Problem:** Agent needs to automatically assign reviewers based on the files changed in an MR.

**Flow:**
```
lore -J mrs 456                           # Get MR details
# Parse file paths from response... but file changes aren't in the output
lore -J who src/path/from/mr/             # Query each path
lore -J who src/another/path/             # One at a time...
lore -J who @candidate --fields minimal   # Check workload
```

**Gap identified:** MR detail view (`mrs <iid>`) doesn't include the file change list from `mr_file_changes`. Agent can't programmatically extract which files an MR touches. Must fall back to GitLab API or guess from description. The `who` command doesn't accept multiple paths. No "auto-reviewer" suggestion combining expertise + availability.

---

### A7. Incident Investigation and Timeline Reconstruction

**Problem:** Agent needs to reconstruct what happened during an outage for a postmortem.

**Flow:**
```
lore -J timeline "outage" --since 3d --depth 2 --expand-mentions
lore -J search "error 500" --since 3d
lore -J mrs -s merged --since 3d -p production-service
lore -J issues --status "In progress" -p production-service
```

**Gap identified:** Timeline is keyword-seeded, which means if the outage wasn't described with that exact term, seeds may miss it. No way to seed a timeline from an entity ID (e.g., "start from issue #321 and expand outward"). No severity/priority filter. No way to correlate with merge times.

---

### A8. Cross-Project Impact Assessment

**Problem:** Agent needs to understand how a breaking API change in project A affects projects B and C.

**Flow:**
```
lore -J search "api-endpoint-name" -p project-a
lore -J search "api-endpoint-name" -p project-b
lore -J search "api-endpoint-name" -p project-c
# Or without project filter to search everywhere:
lore -J search "api-endpoint-name" -n 50
lore -J timeline "api-endpoint-name" --depth 2
```

**Gap identified:** Cross-project references in entity_references are tracked but the timeline shows unresolved references for entities not synced locally. No way to see a cross-project dependency map. Search works across projects but doesn't group results by project.

---

### A9. Automated Stale Issue Recommendations

**Problem:** Agent runs weekly to identify issues that should be closed or re-prioritized.

**Flow:**
```
lore -J issues -s opened --sort updated --asc -n 100  # Oldest first
# For each issue, check:
lore -J issues <iid>                                    # Read details
lore -J search "<issue title keywords>"                 # Any recent activity?
```

**Gap identified:** No `--updated-before` filter, so agent must fetch all and filter client-side. No way to detect "issue has no assignee AND no activity in 90 days." The 100-issue limit means pagination is needed for large backlogs, but there's no cursor/offset pagination -- only `--limit`. Agent must do N+1 queries to inspect each candidate.

---

### A10. Code Review Preparation (File-Level Context)

**Problem:** Agent is reviewing MR !789 and needs to understand the history of each changed file.

**Flow:**
```
lore -J mrs 789                           # Get MR details
# Can't get file list from output...
# Fall back to search by MR title keywords
lore -J search "feature-from-mr" --type mr
lore -J who src/guessed/path/             # Expertise for each file
lore -J who --overlap src/guessed/path/   # Concurrent changes
```

**Gap identified:** Same as A6 -- `mr_file_changes` data isn't exposed. Agent is blind to the actual files in the MR unless it parses the description or uses the GitLab API directly. This is the single biggest gap for automated code review workflows.

---

### A11. Building a Knowledge Graph of Entity Relationships

**Problem:** Agent wants to map how issues, MRs, and discussions are connected for a feature.

**Flow:**
```
lore -J search "feature-name" -n 30
lore -J timeline "feature-name" --depth 2 --max-entities 100
# Timeline shows expanded entities and cross-refs, but...
# No way to query entity_references directly
# No way to get "all entities that reference issue #123"
```

**Gap identified:** The `entity_references` table (closes, related, mentioned) is used internally by timeline but isn't queryable as a standalone command. Agent can't ask "what closes issue #123?" or "what does MR !456 reference?" No graph export. Would enable powerful dependency mapping.

---

### A12. Release Readiness Assessment

**Problem:** Agent needs to verify all issues in milestone "v2.0" are closed and MRs are merged.

**Flow:**
```
lore -J issues -m "v2.0" -s opened       # Any open issues in milestone?
lore -J issues -m "v2.0" -s closed       # Closed issues
# MRs don't have milestone filter...
lore -J mrs -s opened -l "v2.0"          # Try label as proxy
lore -J who --active -p myproject        # Unresolved discussions
```

**Gap identified:** MRs don't have a `--milestone` filter (issues do). No way to check "all MRs linked to issues in milestone v2.0" -- would require joining `entity_references` with issue milestone. No release checklist concept. No way to verify "every issue in this milestone has a closing MR."

---

### A13. Answering "What Changed?" Between Two Points

**Problem:** Agent needs to diff project state between two dates for a stakeholder report.

**Flow:**
```
lore -J issues -s closed --since 2w --fields minimal    # Recently closed
lore -J issues -s opened --since 2w --fields minimal    # Recently opened
lore -J mrs -s merged --since 2w --fields minimal       # Recently merged
# But no way to get "issues that CHANGED STATE" in a window
# An issue opened 3 months ago but closed yesterday won't appear in --since 2w for issues -s opened
```

**Gap identified:** `--since` filters by `updated_at`, not by "state changed at." An issue closed yesterday but created 6 months ago would appear in `issues -s closed --since 1d` (because updated_at changed), but the semantics are subtle. No explicit "state transitions in time window" query. The resource_state_events table has this data but it's not exposed as a filter.

---

### A14. Meeting Prep: Summarize Recent Activity for a Stakeholder

**Problem:** Agent needs to prepare a 2-minute summary for a project sponsor meeting.

**Flow:**
```
lore -J count issues -p project           # Current totals
lore -J count mrs -p project              # MR totals
lore -J issues -s closed --since 1w -p project --fields minimal
lore -J mrs -s merged --since 1w -p project --fields minimal
lore -J issues -s opened --status "In progress" -p project
lore -J who --active -p project --since 1w
```

**Gap identified:** Six queries, same as A3. No summary/dashboard command. Agent must synthesize all responses. No trend data (is the open issue count growing or shrinking?). No "highlights" extraction.

---

### A15. Determining If Work Is Safe to Start (Conflict Detection)

**Problem:** Agent is about to start work on an issue and needs to check nobody else is already working on it.

**Flow:**
```
lore -J issues 123                        # Read the issue
# Check assignees from response
lore -J mrs -s opened -A other-person     # Are they working on related MRs?
lore -J who --overlap src/target/path/    # Anyone actively touching these files?
lore -J search "issue-123-keywords" --type mr -s opened  # Wait, search has no --state
```

**Gap identified:** No way to check "is there an open MR that closes issue #123?" -- the entity_references data exists but isn't queryable. Search doesn't support `--state` filter. No "conflict detection" or "in-flight work" check. Agent must do multiple queries and manually correlate.

---

## Part 3: Gap Summary

### Critical Gaps (high impact, blocks common workflows)

| # | Gap | Affected Flows | Suggested Command/Flag |
|---|-----|----------------|----------------------|
| 1 | **MR file changes not surfaced** | H4, A6, A10 | `lore mrs <iid> --files` or include in detail view |
| 2 | **Entity references not queryable** | H7, A5, A11, A15 | `lore refs --issue 123` / `lore refs --mr 456` |
| 3 | **Per-note search missing** | H7, A4 | `lore search --granularity note` (PRD exists) |
| 4 | **No entity-based timeline** | H11, A7 | `lore timeline --issue 321` / `lore timeline --mr 456` |
| 5 | **No @me / current-user alias** | H1, H15 | Resolve from auth token automatically |

### Important Gaps (significant friction, multiple workarounds needed)

| # | Gap | Affected Flows | Suggested Command/Flag |
|---|-----|----------------|----------------------|
| 6 | **No activity feed / summary** | H1, A3, A14 | `lore activity --since 1d` or `lore summary` |
| 7 | **No multi-path who query** | H6, A6 | `lore who src/path1/ src/path2/` |
| 8 | **No --state filter on search** | H14, A15 | `lore search --state merged` |
| 9 | **MRs missing --milestone filter** | H9, A12 | `lore mrs -m "v2.0"` |
| 10 | **No --no-assignee / --unassigned** | H2 | `lore issues --no-assignee` |
| 11 | **No --updated-before filter** | H10, A9 | `lore issues --before 90d` or `--stale 90d` |
| 12 | **No team workload view** | H8 | `lore who --team` or `lore workload` |

### Nice-to-Have Gaps (would improve agent efficiency)

| # | Gap | Affected Flows | Suggested Command/Flag |
|---|-----|----------------|----------------------|
| 13 | **No pagination/offset** | A9 | `--offset 100` for large result sets |
| 14 | **No detail --fields on show** | A2 | `lore issues 999 --fields description` |
| 15 | **No cross-project grouping** | A8 | `lore search --group-by project` |
| 16 | **No trend/velocity metrics** | A3, A14 | `lore trends issues --period week` |
| 17 | **No --for-issue on mrs** | A12, A15 | `lore mrs --closes 123` (query entity_refs) |
| 18 | **1y/12m duration not supported** | A4 | Support `1y`, `12m`, `365d` in --since |
| 19 | **No discussion participant filter** | H15 | `lore who --active --participant @me` |
| 20 | **No sort by due date** | H2 | `lore issues --sort due` |
