125938fba6
Per-note search PRD: Comprehensive product requirements for evolving the search system from document-level to note-level granularity. Includes 6 rounds of iterative feedback refining scope, ranking strategy, migration path, and robot mode integration. User journeys: Detailed walkthrough of 8 primary user workflows covering issue triage, MR review lookup, code archaeology, expert discovery, sync pipeline operation, and agent integration patterns.
24 KiB
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 |