gitlore/docs/lore-me-spec.md

lore me — Personal Work Dashboard

Overview

A personal dashboard command that shows everything relevant to the configured user: open issues, authored MRs, MRs under review, and recent activity. Attention state is computed from GitLab interaction data (comments) with no local state tracking.

Command Interface

lore me                              # Full dashboard (default project or all)
lore me --issues                     # Issues section only
lore me --mrs                        # MRs section only (authored + reviewing)
lore me --activity                   # Activity feed only
lore me --issues --mrs               # Multiple sections (combinable)
lore me --all                        # All synced projects (overrides default_project)
lore me --since 2d                   # Activity window (default: 30d)
lore me --project group/repo         # Scope to one project
lore me --user jdoe                  # Override configured username

Standard global flags: --robot/-J, --fields, --color, --icons.

---

Acceptance Criteria

AC-1: Configuration

• AC-1.1: New optional field gitlab.username (string) in config.json
• AC-1.2: Resolution order: --user CLI flag > config.gitlab.username > exit code 2 with actionable error message suggesting how to set it
• AC-1.3: Username is case-sensitive (matches GitLab usernames exactly)

AC-2: Command Interface

• AC-2.1: New command lore me — single command with flags (matches who pattern)
• AC-2.2: Section filter flags: --issues, --mrs, --activity — combinable. Passing multiple shows those sections. No flags = full dashboard (all sections).
• AC-2.3: --since <duration> controls activity feed window, default 30 days. Only affects the activity section; work item sections always show all open items regardless of --since.
• AC-2.4: --project <path> scopes to a single project
• AC-2.5: --user <username> overrides configured username
• AC-2.6: --all flag shows all synced projects (overrides default_project)
• AC-2.7: --project and --all are mutually exclusive — passing both is exit code 2
• AC-2.8: Standard global flags: --robot/-J, --fields, --color, --icons

AC-3: "My Items" Definition

• AC-3.1: Issues assigned to me (issue_assignees.username). Authorship alone does NOT qualify an issue.
• AC-3.2: MRs authored by me (merge_requests.author_username)
• AC-3.3: MRs where I'm a reviewer (mr_reviewers.username)
• AC-3.4: Scope is Assigned (issues) + Authored/Reviewing (MRs) — no participation/mention expansion
• AC-3.5: MR assignees (mr_assignees) are NOT used — in Pattern 1 workflows (author = assignee), this is redundant with authorship
• AC-3.6: Activity feed uses CURRENT association only — if you've been unassigned from an issue, activity on it no longer appears. This keeps the query simple and the feed relevant.

AC-4: Attention State Model

• AC-4.1: Computed per-item from synced GitLab data, no local state tracking
• AC-4.2: Interaction signal: notes authored by the user (notes.author_username = me where is_system = 0)
• AC-4.3: Future: award emoji will extend interaction signals (separate bead)
• AC-4.4: States (evaluated in this order — first match wins):
  1. not_ready: MR only — draft=1 AND zero entries in mr_reviewers
  2. needs_attention: Others' latest non-system note > user's latest non-system note
  3. stale: Entity has at least one non-system note from someone, but the most recent note from anyone is older than 30 days. Items with ZERO notes are NOT stale — they're not_started.
  4. not_started: User has zero non-system notes on this entity (regardless of whether others have commented)
  5. awaiting_response: User's latest non-system note timestamp >= all others' latest non-system note timestamps (including when user is the only commenter)
• AC-4.5: Applied to all item types (issues, authored MRs, reviewing MRs)

AC-5: Dashboard Sections

AC-5.1: Open Issues

• Source: issue_assignees.username = me, state = opened
• Fields: project path, iid, title, status_name (work item status), attention state, relative time since updated
• Sort: attention-first (needs_attention > not_started > awaiting_response > stale), then most recently updated within same state
• No limit, no truncation — show all

AC-5.2: Open MRs — Authored

• Source: merge_requests.author_username = me, state = opened
• Fields: project path, iid, title, draft indicator, detailed_merge_status, attention state, relative time
• Sort: same as issues

AC-5.3: Open MRs — Reviewing

• Source: mr_reviewers.username = me, state = opened
• Fields: project path, iid, title, MR author username, draft indicator, attention state, relative time
• Sort: same as issues

AC-5.4: Activity Feed

• Sources (all within --since window, default 30d):
  • Human comments (notes.is_system = 0) on my items
  • State events (resource_state_events) on my items
  • Label events (resource_label_events) on my items
  • Milestone events (resource_milestone_events) on my items
  • Assignment/reviewer system notes (see AC-12 for patterns) on my items
• "My items" for the activity feed = items I'm CURRENTLY associated with per AC-3 (current assignment state, not historical)
• Includes activity on items regardless of open/closed state
• Own actions included but flagged (is_own: true in robot, (you) suffix + dimmed in human)
• Sort: newest first (chronological descending)
• No limit, no truncation — show all events

AC-5.5: Summary Header

• Counts: projects, open issues, authored MRs, reviewing MRs, needs_attention count
• Attention legend (human mode): icon + label for each state

AC-6: Human Output — Visual Design

AC-6.1: Layout

• Section card style with section_divider headers
• Legend at top explains attention icons
• Two-line per item: main data on line 1, project path on line 2 (indented)
• When scoped to single project (--project), suppress project path line (redundant)

AC-6.2: Attention Icons (three tiers)

State	Nerd Font	Unicode	ASCII	Color
needs_attention	\uf0f3 bell	◆	[!]	amber (warning)
not_started	\uf005 star	★	[*]	cyan (info)
awaiting_response	\uf017 clock	◷	[~]	dim (muted)
stale	\uf54c skull	☠	[x]	dim (muted)

AC-6.3: Color Vocabulary (matches existing lore palette)

• Issue refs (#N): cyan
• MR refs (!N): purple
• Usernames (@name): cyan
• Opened state: green
• Merged state: purple
• Closed state: dim
• Draft indicator: gray
• Own actions: dimmed + (you) suffix
• Timestamps: dim (relative time)

AC-6.4: Activity Event Badges

Event	Nerd/Unicode (colored bg)	ASCII fallback
note	cyan bg, dark text	[note] cyan text
status	amber bg, dark text	[status] amber text
label	purple bg, white text	[label] purple text
assign	green bg, dark text	[assign] green text
milestone	magenta bg, white text	[milestone] magenta text

Fallback: when background colors aren't available (ASCII mode), use colored text with brackets instead of background pills.

AC-6.5: Labels

• Human mode: not shown
• Robot mode: included in JSON

AC-7: Robot Output

• AC-7.1: Standard {ok, data, meta} envelope
• AC-7.2: data contains: username, since_iso, summary (counts + needs_attention_count), open_issues[], open_mrs_authored[], reviewing_mrs[], activity[]
• AC-7.3: Each item includes: project, iid, title, state, attention_state (programmatic: needs_attention, not_started, awaiting_response, stale, not_ready), labels, updated_at_iso, web_url
• AC-7.4: Issues include status_name (work item status)
• AC-7.5: MRs include draft, detailed_merge_status, author_username (reviewing section)
• AC-7.6: Activity items include: timestamp_iso, event_type, entity_type, entity_iid, project, actor, is_own, summary, body_preview (for notes, truncated to 200 chars)
• AC-7.7: --fields minimal preset: iid, title, attention_state, updated_at_iso (work items); timestamp_iso, event_type, entity_iid, actor (activity)
• AC-7.8: Metadata-only depth — agents drill into specific items with timeline, issues, mrs for full context
• AC-7.9: No limits, no truncation on any array

AC-8: Cross-Project Behavior

• AC-8.1: If config.default_project is set, scope to that project by default. If no default project, show all synced projects.
• AC-8.2: --all flag overrides default project and shows all synced projects
• AC-8.3: --project flag narrows to a specific project (supports fuzzy match like other commands)
• AC-8.4: --project and --all are mutually exclusive (exit 2 if both passed)
• AC-8.5: Project path shown per-item in both human and robot output (suppressed in human when single-project scoped per AC-6.1)

AC-9: Sort Order

• AC-9.1: Work item sections: attention-first, then most recently updated
• AC-9.2: Attention priority: needs_attention > not_started > awaiting_response > stale > not_ready
• AC-9.3: Activity feed: chronological descending (newest first)

AC-10: Error Handling

• AC-10.1: No username configured and no --user flag → exit 2 with suggestion
• AC-10.2: No synced data → exit 17 with suggestion to run lore sync
• AC-10.3: Username found but no matching items → empty sections with summary showing zeros
• AC-10.4: --project and --all both passed → exit 2 with message

AC-11: Relationship to Existing Commands

• AC-11.1: who @username remains for looking at anyone's workload
• AC-11.2: lore me is the self-view with attention intelligence
• AC-11.3: No deprecation of who — they serve different purposes

AC-12: New Assignments Detection

• AC-12.1: Detect from system notes (notes.is_system = 1) matching these body patterns:
  • "assigned to @username" — issue/MR assignment
  • "unassigned @username" — removal (shown as unassign event type)
  • "requested review from @username" — reviewer assignment (shown as review_request event type)
• AC-12.2: These appear in the activity feed with appropriate event types
• AC-12.3: Shows who performed the action (note author from the associated non-system context, or "system" if unavailable) and when (note created_at)
• AC-12.4: Pattern matching is case-insensitive and matches username at word boundary

---

Out of Scope (Follow-Up Work)

• Award emoji sync: Extends attention signal with reaction timestamps. Requires new table + GitLab REST API integration. Note-level emoji sync has N+1 concern requiring smart batching.
• Participation/mention expansion: Broadening "my items" beyond assigned+authored.
• Label filtering: --label flag to scope dashboard by label.

---

Design Notes

Why No High-Water Mark

GitLab itself is the source of truth for "what I've engaged with." The attention state is computed by comparing the user's latest comment timestamp against others' latest comment timestamps on each item. No local cursor or mark is needed.

Why Comments-Only (For Now)

Award emoji (reactions) are a valid "I've engaged" signal but aren't currently synced. The attention model is designed to incorporate emoji timestamps when available — adding them later requires no model changes.

Why MR Assignees Are Excluded

GitLab MR workflows have three role fields: Author, Assignee, and Reviewer. In Pattern 1 workflows (the most common post-2020), the author assigns themselves — making assignee redundant with authorship. The Reviewing section uses mr_reviewers as the review signal.

Attention State Evaluation Order

States are evaluated in priority order (first match wins):

1. not_ready    — MR-only: draft=1 AND no reviewers
2. needs_attention — others commented after me
3. stale        — had activity, but nothing in 30d (NOT for zero-comment items)
4. not_started  — I have zero comments (may or may not have others' comments)
5. awaiting_response — I commented last (or I'm the only commenter)

Edge cases:

• Zero comments from anyone → not_started (NOT stale)
• Only my comments, none from others → awaiting_response
• Only others' comments, none from me → not_started (I haven't engaged)
  • Wait: this conflicts with needs_attention (step 2). If others have commented and I haven't, then others' latest > my latest (NULL). This should be needs_attention, not not_started.

Corrected logic:

• needs_attention takes priority over not_started when others HAVE commented but I haven't. The distinction: not_started only applies when NOBODY has commented.

1. not_ready         — MR-only: draft=1 AND no reviewers
2. needs_attention   — others have non-system notes AND (I have none OR others' latest > my latest)
3. stale             — latest note from anyone is older than 30 days
4. awaiting_response — my latest >= others' latest (I'm caught up)
5. not_started       — zero non-system notes from anyone

Attention State Computation (SQL Sketch)

WITH my_latest AS (
    SELECT d.issue_id, d.merge_request_id, MAX(n.created_at) AS ts
    FROM notes n
    JOIN discussions d ON n.discussion_id = d.id
    WHERE n.author_username = ?me AND n.is_system = 0
    GROUP BY d.issue_id, d.merge_request_id
),
others_latest AS (
    SELECT d.issue_id, d.merge_request_id, MAX(n.created_at) AS ts
    FROM notes n
    JOIN discussions d ON n.discussion_id = d.id
    WHERE n.author_username != ?me AND n.is_system = 0
    GROUP BY d.issue_id, d.merge_request_id
),
any_latest AS (
    SELECT d.issue_id, d.merge_request_id, MAX(n.created_at) AS ts
    FROM notes n
    JOIN discussions d ON n.discussion_id = d.id
    WHERE n.is_system = 0
    GROUP BY d.issue_id, d.merge_request_id
)
SELECT
    CASE
        -- MR-only: draft with no reviewers
        WHEN entity_type = 'mr' AND draft = 1
             AND NOT EXISTS (SELECT 1 FROM mr_reviewers WHERE merge_request_id = entity_id)
            THEN 'not_ready'
        -- Others commented and I haven't caught up (or never engaged)
        WHEN others.ts IS NOT NULL AND (my.ts IS NULL OR others.ts > my.ts)
            THEN 'needs_attention'
        -- Had activity but gone quiet for 30d
        WHEN any.ts IS NOT NULL AND any.ts < ?now_minus_30d
            THEN 'stale'
        -- I've responded and I'm caught up
        WHEN my.ts IS NOT NULL AND my.ts >= COALESCE(others.ts, 0)
            THEN 'awaiting_response'
        -- Nobody has commented at all
        ELSE 'not_started'
    END AS attention_state
FROM ...