gitlore/docs/ideas/project-ergonomics.md

Multi-Project Ergonomics

• Confidence: 90%
• Tier: 1
• Status: proposed
• Effort: medium (multiple small improvements that compound)

The Problem

Every command that touches project-scoped data requires -p group/subgroup/project to disambiguate. For users with 5+ projects synced, this is:

• Repetitive: typing -p infra/platform/auth-service on every query
• Error-prone: mistyping long paths
• Discoverable only by failure: you don't know you need -p until you hit an ambiguous error

The fuzzy matching in resolve_project is already good (suffix, substring, case-insensitive) but it only kicks in on the -p value itself. There's no way to set a default, group projects, or scope a whole session.

Proposed Improvements

1. Project Aliases in Config

Let users define short aliases for long project paths.

{
  "projects": [
    { "path": "infra/platform/auth-service", "alias": "auth" },
    { "path": "infra/platform/billing-service", "alias": "billing" },
    { "path": "frontend/customer-portal", "alias": "portal" },
    { "path": "frontend/admin-dashboard", "alias": "admin" }
  ]
}

Then: lore issues -p auth resolves via alias before falling through to fuzzy match.

Implementation: Add optional alias field to ProjectConfig. In resolve_project, check aliases before the existing exact/suffix/substring cascade.

#[derive(Debug, Clone, Deserialize)]
pub struct ProjectConfig {
    pub path: String,
    #[serde(default)]
    pub alias: Option<String>,
}

Resolution order becomes:

1. Exact alias match (new)
2. Exact path match
3. Case-insensitive path match
4. Suffix match
5. Substring match

2. Default Project (LORE_PROJECT env var)

Set a default project for your shell session so you don't need -p at all.

export LORE_PROJECT=auth
lore issues                   # scoped to auth-service
lore mrs --state opened       # scoped to auth-service
lore search "timeout bug"     # scoped to auth-service
lore issues -p billing        # explicit -p overrides the env var

Implementation: In every command that accepts -p, fall back to std::env::var("LORE_PROJECT") when the flag is absent. The -p flag always wins.

Could also support a config-level default:

{
  "defaultProject": "auth"
}

Precedence: CLI flag > env var > config default > (no filter).

3. lore use <project> — Session Context Switcher

A command that sets LORE_PROJECT for the current shell by writing to a dotfile.

lore use auth
# writes ~/.local/state/lore/current-project containing "auth"

lore issues        # reads current-project file, scopes to auth
lore use --clear   # removes the file, back to all-project mode
lore use           # shows current project context

This is similar to kubectl config use-context, nvm use, or tfenv use.

Implementation: Write a one-line file at a known state path. Each command reads it as the lowest-priority default (below env var and CLI flag).

Precedence: CLI flag > env var > lore use state file > config default > (no filter).

4. lore projects — Project Listing and Discovery

A dedicated command to see what's synced, with aliases and activity stats.

$ lore projects

  Alias    Path                              Issues   MRs   Last Sync
  auth     infra/platform/auth-service          142    87   2h ago
  billing  infra/platform/billing-service        56    34   2h ago
  portal   frontend/customer-portal             203   112   2h ago
  admin    frontend/admin-dashboard              28    15   3d ago
  -        data/ml-pipeline                      89    45   2h ago

Robot mode returns the same as JSON with alias, path, counts, and last sync time.

Implementation: Query projects joined with COUNT(issues), COUNT(mrs), and MAX(sync_runs.finished_at). Overlay aliases from config.

5. Project Groups in Config

Let users define named groups of projects for batch scoping.

{
  "projectGroups": {
    "backend": ["auth", "billing", "data/ml-pipeline"],
    "frontend": ["portal", "admin"],
    "all-infra": ["auth", "billing"]
  }
}

Then: lore issues -p @backend (or --group backend) queries across all projects in the group.

Implementation: When -p value starts with @, look up the group and resolve each member project. Pass as a Vec<i64> of project IDs to the query layer.

This is especially powerful for:

• lore search "auth bug" -p @backend — search across related repos
• lore digest --since 7d -p @frontend — team-scoped activity digest
• lore timeline "deployment" -p @all-infra — cross-repo timeline

6. Git-Aware Project Detection

When running lore from inside a git repo that matches a synced project, auto-scope to that project without any flags.

cd ~/code/auth-service
lore issues                   # auto-detects this is infra/platform/auth-service

Implementation: Read .git/config for the remote URL, extract the project path, check if it matches a synced project. Only activate when exactly one project matches.

Detection logic:

1. Check if cwd is inside a git repo (find .git)
2. Parse git remote origin URL
3. Extract path component (e.g., "infra/platform/auth-service.git" → "infra/platform/auth-service")
4. Match against synced projects
5. If exactly one match, use as implicit -p
6. If ambiguous or no match, do nothing (fall through to normal behavior)

Precedence: CLI flag > env var > lore use > config default > git detection > (no filter).

This is similar to how gh (GitHub CLI) auto-detects the repo you're in.

7. Prompt Integration / Shell Function

Provide a shell function that shows the current project context in the prompt.

# In .bashrc / .zshrc
eval "$(lore completions zsh)"
PROMPT='$(lore-prompt)%~ %# '

Output: [lore:auth] ~/code/auth-service %

Shows which project lore commands will scope to, using the same precedence chain. Helps users understand what context they're in before running a query.

8. Short Project References in Output

Once aliases exist, use them everywhere in output for brevity:

Before:

infra/platform/auth-service#42  Login timeout bug
infra/platform/auth-service!234 Refactor auth middleware

After:

auth#42   Login timeout bug
auth!234  Refactor auth middleware

With --full-paths flag to get the verbose form when needed.

Combined UX Flow

With all improvements, a typical session looks like:

# One-time config
lore init   # sets up aliases during interactive setup

# Daily use
lore use auth                              # set context
lore issues --state opened                 # no -p needed
lore search "timeout"                      # scoped to auth
lore timeline "login flow"                 # scoped to auth
lore issues -p @backend                    # cross-repo query via group
lore mrs -p billing                        # quick alias switch
lore use --clear                           # back to global

Or for the power user who never wants to type lore use:

cd ~/code/auth-service
lore issues                                # git-aware auto-detection

Or for the scripter:

LORE_PROJECT=auth lore --robot issues -n 50  # env var for automation

Priority Order

Implement in this order for maximum incremental value:

1. Project aliases — smallest change, biggest daily friction reduction
2. LORE_PROJECT env var — trivial to implement, enables scripting
3. lore projects command — discoverability, completes the alias story
4. lore use context — nice-to-have for heavy users
5. Project groups — high value for multi-repo teams
6. Git-aware detection — polish, "it just works" feel
7. Short refs in output — ties into timeline issue #001
8. Prompt integration — extra polish

Relationship to Issue #001

The timeline entity-ref ambiguity (issue #001) is solved naturally by items 7 and 8 here. Once aliases exist, format_entity_ref can use the alias as the short project identifier in multi-project output:

auth#42    instead of    infra/platform/auth-service#42

And in single-project timelines (detected via lore use or git-aware), the project prefix is omitted entirely — matching the current behavior but now intentionally.