# Spec: lore explain — Auto-Generated Issue/MR Narratives

**Bead:** bd-9lbr
**Created:** 2026-03-10

## Spec Status
| Section | Status | Notes |
|---------|--------|-------|
| Objective | complete | |
| Tech Stack | complete | |
| Project Structure | complete | |
| Commands | complete | |
| Code Style | complete | UX-audited: after_help, --sections, --since, --no-timeline, --max-decisions, singular types |
| Boundaries | complete | |
| Testing Strategy | complete | 13 test cases (7 original + 5 UX flags + 1 singular type) |
| Git Workflow | complete | jj-first |
| User Journeys | complete | 3 journeys covering agent, human, pipeline use |
| Architecture | complete | ExplainParams + section filtering + time scoping |
| Success Criteria | complete | 15 criteria (10 original + 5 UX flags) |
| Non-Goals | complete | |
| Tasks | complete | 5 tasks across 3 phases, all updated for UX flags |

**Definition of Complete:** All sections `complete`, Open Questions empty,
every user journey has tasks, every task has TDD workflow and acceptance criteria.

---

## Quick Reference
- [Entity Detail] (Architecture): reuse show/ query patterns (private — copy, don't import)
- [Timeline] (Architecture): import `crate::timeline::seed::seed_timeline_direct` + `collect_events`
- [Events] (Architecture): new inline queries against resource_state_events/resource_label_events
- [References] (Architecture): new query against entity_references table
- [Discussions] (Architecture): adapted from show/ patterns, add resolved/resolvable filter

---

## Open Questions (Resolve Before Implementation)
<!-- All resolved -->

---

## Objective

**Goal:** Add `lore explain issues N` / `lore explain mrs N` to auto-generate structured narratives of what happened on an issue or MR.

**Problem:** Understanding the full story of an issue/MR requires reading dozens of notes, cross-referencing state changes, checking related entities, and piecing together a timeline. This is time-consuming for humans and nearly impossible for AI agents without custom orchestration.

**Success metrics:**
- Produces a complete narrative in <500ms for an issue with 50 notes
- All 7 sections populated (entity, description_excerpt, key_decisions, activity, open_threads, related, timeline_excerpt)
- Works fully offline (no API calls, no LLM)
- Deterministic and reproducible (same input = same output)

---

## Tech Stack & Constraints

| Layer | Technology | Version |
|-------|-----------|---------|
| Language | Rust | nightly-2026-03-01 (rust-toolchain.toml) |
| Framework | clap (derive) | As in Cargo.toml |
| Database | SQLite via rusqlite | Bundled |
| Testing | cargo test | Inline #[cfg(test)] |
| Async | asupersync | 0.2 |

**Constraints:**
- No LLM dependency — template-based, deterministic
- No network calls — all data from local SQLite
- Performance: <500ms for 50-note entity
- Unsafe code forbidden (`#![forbid(unsafe_code)]`)

---

## Project Structure

```
src/cli/commands/
  explain.rs            # NEW: command module (queries, heuristic, result types)
src/cli/
  mod.rs                # EDIT: add Explain variant to Commands enum
src/app/
  handlers.rs           # EDIT: add handle_explain dispatch
  robot_docs.rs         # EDIT: register explain in robot-docs manifest
src/main.rs             # EDIT: add Explain match arm
```

---

## Commands

```bash
# Build
cargo check --all-targets

# Test
cargo test explain

# Lint
cargo clippy --all-targets -- -D warnings

# Format
cargo fmt --check
```

---

## Code Style

**Command registration (from cli/mod.rs):**
```rust
/// Auto-generate a structured narrative of an issue or MR
#[command(after_help = "\x1b[1mExamples:\x1b[0m
  lore explain issues 42                  # Narrative for issue #42
  lore explain mrs 99 -p group/repo       # Narrative for MR !99 in specific project
  lore -J explain issues 42               # JSON output for automation
  lore explain issues 42 --sections key_decisions,open_threads  # Specific sections only
  lore explain issues 42 --since 30d      # Narrative scoped to last 30 days
  lore explain issues 42 --no-timeline    # Skip timeline (faster)")]
Explain {
    /// Entity type: "issues" or "mrs" (singular forms also accepted)
    #[arg(value_parser = ["issues", "mrs", "issue", "mr"])]
    entity_type: String,

    /// Entity IID
    iid: i64,

    /// Scope to project (fuzzy match)
    #[arg(short, long)]
    project: Option<String>,

    /// Select specific sections (comma-separated)
    /// Valid: entity, description, key_decisions, activity, open_threads, related, timeline
    #[arg(long, value_delimiter = ',', help_heading = "Output")]
    sections: Option<Vec<String>>,

    /// Skip timeline excerpt (faster execution)
    #[arg(long, help_heading = "Output")]
    no_timeline: bool,

    /// Maximum key decisions to include
    #[arg(long, default_value = "10", help_heading = "Output")]
    max_decisions: usize,

    /// Time scope for events/notes (e.g. 7d, 2w, 1m, or YYYY-MM-DD)
    #[arg(long, help_heading = "Filters")]
    since: Option<String>,
},
```

**Entity type normalization:** The handler must normalize singular forms: `"issue"` -> `"issues"`, `"mr"` -> `"mrs"`. This prevents common typos from causing errors.

**Query pattern (from show/issue.rs):**
```rust
fn find_issue(conn: &Connection, iid: i64, project_filter: Option<&str>) -> Result<IssueRow> {
    let project_id = resolve_project(conn, project_filter)?;
    let mut stmt = conn.prepare_cached("SELECT ... FROM issues WHERE iid = ?1 AND project_id = ?2")?;
    // ...
}
```

**Robot mode output (from cli/robot.rs):**
```rust
let response = serde_json::json!({
    "ok": true,
    "data": result,
    "meta": { "elapsed_ms": elapsed.as_millis() }
});
println!("{}", serde_json::to_string(&response)?);
```

---

## Boundaries

### Always (autonomous)
- Run `cargo test explain` and `cargo clippy` after every code change
- Follow existing query patterns from show/issue.rs and show/mr.rs
- Use `resolve_project()` for project resolution (fuzzy match)
- Cap key_decisions at `--max-decisions` (default 10), timeline_excerpt at 20 events
- Normalize singular entity types (`issue` -> `issues`, `mr` -> `mrs`)
- Respect `--sections` filter: omit unselected sections from output (both robot and human)
- Respect `--since` filter: scope events/notes queries with `created_at >= ?` threshold

### Ask First (needs approval)
- Adding new dependencies to Cargo.toml
- Modifying existing query functions in show/ or timeline/
- Changing the entity_references table schema

### Never (hard stops)
- No LLM calls — explain must be deterministic
- No API/network calls — fully offline
- No new database migrations — use existing schema only
- Do not modify show/ or timeline/ modules (copy patterns instead)

---

## Testing Strategy (TDD — Red-Green)

**Methodology:** Test-Driven Development. Write tests first, confirm red, implement, confirm green.

**Framework:** cargo test, inline `#[cfg(test)]`
**Location:** `src/cli/commands/explain.rs` (inline test module)

**Test categories:**
- Unit tests: key-decisions heuristic, activity counting, description truncation
- Integration tests: full explain pipeline with in-memory DB

**User journey test mapping:**
| Journey | Test | Scenarios |
|---------|------|-----------|
| UJ-1: Agent explains issue | test_explain_issue_basic | All 7 sections present, robot JSON valid |
| UJ-1: Agent explains MR | test_explain_mr | entity.type = "merge_request", merged_at included |
| UJ-1: Singular entity type | test_explain_singular_entity_type | `"issue"` normalizes to `"issues"` |
| UJ-1: Section filtering | test_explain_sections_filter_robot | Only selected sections in output |
| UJ-1: No-timeline flag | test_explain_no_timeline_flag | timeline_excerpt is None |
| UJ-2: Human reads narrative | (human render tested manually) | Headers, indentation, color |
| UJ-3: Key decisions | test_explain_key_decision_heuristic | Note within 60min of state change by same actor |
| UJ-3: No false decisions | test_explain_key_decision_ignores_unrelated_notes | Different author's note excluded |
| UJ-3: Max decisions cap | test_explain_max_decisions | Respects `--max-decisions` parameter |
| UJ-3: Since scopes events | test_explain_since_scopes_events | Only recent events included |
| UJ-3: Open threads | test_explain_open_threads | Only unresolved discussions in output |
| UJ-3: Edge case | test_explain_no_notes | Empty sections, no panic |
| UJ-3: Activity counts | test_explain_activity_counts | Correct state/label/note counts |

---

## Git Workflow

- **jj-first** — all VCS via jj, not git
- **Commit format:** `feat(explain): <description>`
- **No branches** — commit in place, use jj bookmarks to push

---

## User Journeys (Prioritized)

### P1 — Critical
- **UJ-1: Agent queries issue/MR narrative**
  - Actor: AI agent (via robot mode)
  - Flow: `lore -J explain issues 42` → JSON with 7 sections → agent parses and acts
  - Error paths: Issue not found (exit 17), ambiguous project (exit 18)
  - Implemented by: Task 1, 2, 3, 4

### P2 — Important
- **UJ-2: Human reads explain output**
  - Actor: Developer at terminal
  - Flow: `lore explain issues 42` → formatted narrative with headers, colors, indentation
  - Error paths: Same as UJ-1 but with human-readable error messages
  - Implemented by: Task 5

### P3 — Nice to Have
- **UJ-3: Agent uses key-decisions to understand context**
  - Actor: AI agent making decisions
  - Flow: Parse `key_decisions` array → understand who decided what and when → inform action
  - Error paths: No key decisions found (empty array, not error)
  - Implemented by: Task 3

---

## Architecture / Data Model

### Data Assembly Pipeline (sync, no async needed)

```
1. RESOLVE    → resolve_project() + find entity by IID
2. PARSE      → normalize entity_type, parse --since, validate --sections
3. DETAIL     → entity metadata (title, state, author, labels, assignees, status)
4. EVENTS     → resource_state_events + resource_label_events (optionally --since scoped)
5. NOTES      → non-system notes via discussions join (optionally --since scoped)
6. HEURISTIC  → key_decisions = events correlated with notes by same actor within 60min
7. THREADS    → discussions WHERE resolvable=1 AND resolved=0
8. REFERENCES → entity_references (both directions: source and target)
9. TIMELINE   → seed_timeline_direct + collect_events (capped at 20, skip if --no-timeline)
10. FILTER    → apply --sections filter: drop unselected sections before serialization
11. ASSEMBLE  → combine into ExplainResult
```

**Section filtering:** When `--sections` is provided, only the listed sections are populated.
Unselected sections are set to their zero-value (`None`, empty vec, etc.) and omitted
from robot JSON via `#[serde(skip_serializing_if = "...")]`. The `entity` section is always
included (needed for identification). Human mode skips rendering unselected sections.

**Time scoping:** When `--since` is provided, parse it using `crate::core::time::parse_since()`
(same function used by timeline, me, file-history). Add `AND created_at >= ?` to events
and notes queries. The entity header, references, and open threads are NOT time-scoped
(they represent current state, not historical events).

### Key Types

```rust
/// Parameters controlling explain behavior.
pub struct ExplainParams {
    pub entity_type: String,       // "issues" or "mrs" (already normalized)
    pub iid: i64,
    pub project: Option<String>,
    pub sections: Option<Vec<String>>,  // None = all sections
    pub no_timeline: bool,
    pub max_decisions: usize,      // default 10
    pub since: Option<i64>,        // ms epoch threshold from --since parsing
}

#[derive(Debug, Serialize)]
pub struct ExplainResult {
    pub entity: EntitySummary,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description_excerpt: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub key_decisions: Option<Vec<KeyDecision>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub activity: Option<ActivitySummary>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub open_threads: Option<Vec<OpenThread>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub related: Option<RelatedEntities>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub timeline_excerpt: Option<Vec<TimelineEventSummary>>,
}

#[derive(Debug, Serialize)]
pub struct EntitySummary {
    #[serde(rename = "type")]
    pub entity_type: String,    // "issue" or "merge_request"
    pub iid: i64,
    pub title: String,
    pub state: String,
    pub author: String,
    pub assignees: Vec<String>,
    pub labels: Vec<String>,
    pub created_at: String,     // ISO 8601
    pub updated_at: String,     // ISO 8601
    pub url: Option<String>,
    pub status_name: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct KeyDecision {
    pub timestamp: String,      // ISO 8601
    pub actor: String,
    pub action: String,         // "state: opened -> closed" or "label: +bug"
    pub context_note: String,   // truncated to 500 chars
}

#[derive(Debug, Serialize)]
pub struct ActivitySummary {
    pub state_changes: usize,
    pub label_changes: usize,
    pub notes: usize,           // non-system only
    pub first_event: Option<String>,   // ISO 8601
    pub last_event: Option<String>,    // ISO 8601
}

#[derive(Debug, Serialize)]
pub struct OpenThread {
    pub discussion_id: String,
    pub started_by: String,
    pub started_at: String,     // ISO 8601
    pub note_count: usize,
    pub last_note_at: String,   // ISO 8601
}

#[derive(Debug, Serialize)]
pub struct RelatedEntities {
    pub closing_mrs: Vec<ClosingMrInfo>,
    pub related_issues: Vec<RelatedEntityInfo>,
}

#[derive(Debug, Serialize)]
pub struct TimelineEventSummary {
    pub timestamp: String,      // ISO 8601
    pub event_type: String,
    pub actor: Option<String>,
    pub summary: String,
}
```

### Key Decisions Heuristic

The heuristic identifies notes that explain WHY state/label changes were made:

1. Collect all `resource_state_events` and `resource_label_events` for the entity
2. Merge into unified chronological list with (timestamp, actor, description)
3. For each event, find the FIRST non-system note by the SAME actor within 60 minutes AFTER the event
4. Pair them as a `KeyDecision`
5. Cap at `params.max_decisions` (default 10)

**SQL for state events:**
```sql
SELECT state, actor_username, created_at
FROM resource_state_events
WHERE issue_id = ?1   -- or merge_request_id = ?1
  AND (?2 IS NULL OR created_at >= ?2)   -- --since filter
ORDER BY created_at ASC
```

**SQL for label events:**
```sql
SELECT action, label_name, actor_username, created_at
FROM resource_label_events
WHERE issue_id = ?1   -- or merge_request_id = ?1
  AND (?2 IS NULL OR created_at >= ?2)   -- --since filter
ORDER BY created_at ASC
```

**SQL for non-system notes (for correlation):**
```sql
SELECT n.body, n.author_username, n.created_at
FROM notes n
JOIN discussions d ON n.discussion_id = d.id
WHERE d.noteable_type = ?1 AND d.issue_id = ?2   -- or d.merge_request_id
  AND n.is_system = 0
  AND (?3 IS NULL OR n.created_at >= ?3)   -- --since filter
ORDER BY n.created_at ASC
```

**Entity ID resolution:** The `discussions` table uses `issue_id` / `merge_request_id` columns (CHECK constraint: exactly one non-NULL). The `resource_state_events` and `resource_label_events` tables use the same pattern.

### Cross-References Query

```sql
-- Outgoing references (this entity references others)
SELECT target_entity_type, target_entity_id, target_project_path,
       target_entity_iid, reference_type, source_method
FROM entity_references
WHERE source_entity_type = ?1 AND source_entity_id = ?2

-- Incoming references (others reference this entity)
SELECT source_entity_type, source_entity_id,
       reference_type, source_method
FROM entity_references
WHERE target_entity_type = ?1 AND target_entity_id = ?2
```

**Note:** For closing MRs, reuse the pattern from show/issue.rs `get_closing_mrs()` which queries entity_references with `reference_type = 'closes'`.

### Open Threads Query

```sql
SELECT d.gitlab_discussion_id, d.first_note_at, d.last_note_at
FROM discussions d
WHERE d.issue_id = ?1   -- or d.merge_request_id
  AND d.resolvable = 1
  AND d.resolved = 0
ORDER BY d.last_note_at DESC
```

Then for each discussion, fetch the first note's author:
```sql
SELECT author_username, created_at
FROM notes
WHERE discussion_id = ?1
ORDER BY created_at ASC
LIMIT 1
```

And count notes per discussion:
```sql
SELECT COUNT(*) FROM notes WHERE discussion_id = ?1 AND is_system = 0
```

### Robot Mode Output Schema

```json
{
  "ok": true,
  "data": {
    "entity": {
      "type": "issue", "iid": 3864, "title": "...", "state": "opened",
      "author": "teernisse", "assignees": ["teernisse"],
      "labels": ["customer:BNSF"], "created_at": "2026-01-10T...",
      "updated_at": "2026-02-12T...", "url": "...", "status_name": "In progress"
    },
    "description_excerpt": "First 500 chars...",
    "key_decisions": [{
      "timestamp": "2026-01-15T...",
      "actor": "teernisse",
      "action": "state: opened -> closed",
      "context_note": "Starting work on the integration..."
    }],
    "activity": {
      "state_changes": 3, "label_changes": 5, "notes": 42,
      "first_event": "2026-01-10T...", "last_event": "2026-02-12T..."
    },
    "open_threads": [{
      "discussion_id": "abc123",
      "started_by": "cseiber",
      "started_at": "2026-02-01T...",
      "note_count": 5,
      "last_note_at": "2026-02-10T..."
    }],
    "related": {
      "closing_mrs": [{ "iid": 200, "title": "...", "state": "merged" }],
      "related_issues": [{ "iid": 3800, "title": "Rail Break Card", "type": "related" }]
    },
    "timeline_excerpt": [
      { "timestamp": "...", "event_type": "state_changed", "actor": "teernisse", "summary": "State changed to closed" }
    ]
  },
  "meta": { "elapsed_ms": 350 }
}
```

---

## Success Criteria

| # | Criterion | Input | Expected Output |
|---|-----------|-------|----------------|
| 1 | Issue explain produces all 7 sections | `lore -J explain issues N` | JSON with entity, description_excerpt, key_decisions, activity, open_threads, related, timeline_excerpt |
| 2 | MR explain produces all 7 sections | `lore -J explain mrs N` | Same shape, entity.type = "merge_request" |
| 3 | Key decisions captures correlated notes | State change + note by same actor within 60min | KeyDecision with action + context_note |
| 4 | Key decisions ignores unrelated notes | Note by different author near state change | Not in key_decisions array |
| 5 | Open threads filters correctly | 2 discussions: 1 resolved, 1 unresolved | Only unresolved in open_threads |
| 6 | Activity counts are accurate | 3 state events, 2 label events, 10 notes | Matching counts in activity section |
| 7 | Performance | Issue with 50 notes | <500ms |
| 8 | Entity not found | Non-existent IID | Exit code 17, suggestion to sync |
| 9 | Ambiguous project | IID exists in multiple projects, no -p | Exit code 18, suggestion to use -p |
| 10 | Human render | `lore explain issues N` (no -J) | Formatted narrative with headers |
| 11 | Singular entity type accepted | `lore explain issue 42` | Same as `lore explain issues 42` |
| 12 | Section filtering works | `--sections key_decisions,activity` | Only those 2 sections + entity in JSON |
| 13 | No-timeline skips timeline | `--no-timeline` | timeline_excerpt absent, faster execution |
| 14 | Max-decisions caps output | `--max-decisions 3` | At most 3 key_decisions |
| 15 | Since scopes events/notes | `--since 30d` | Only events/notes from last 30 days in activity, key_decisions |

---

## Non-Goals

- **No LLM summarization** — This is template-based v1. LLM enhancement is a separate future feature.
- **No new database migrations** — Uses existing schema (resource_state_events, resource_label_events, discussions, notes, entity_references tables all exist).
- **No modification of show/ or timeline/ modules** — Copy patterns, don't refactor existing code. If we later want to share code, that's a separate refactoring bead.
- **No interactive mode** — Output only, no prompts or follow-up questions.
- **No MR diff analysis** — No file-level change summaries. Use `file-history` or `trace` for that.
- **No assignee/reviewer history** — Activity summary counts events but doesn't track assignment changes over time.

---

## Tasks

### Phase 1: Setup & Registration

- [ ] **Task 1:** Register explain command in CLI and wire dispatch
  - **Implements:** Infrastructure (UJ-1, UJ-2 prerequisite)
  - **Files:** `src/cli/mod.rs`, `src/cli/commands/mod.rs`, `src/main.rs`, `src/app/handlers.rs`, NEW `src/cli/commands/explain.rs`
  - **Depends on:** Nothing
  - **Test-first:**
    1. Write `test_explain_issue_basic` in explain.rs: insert a minimal issue + project + 1 discussion + 1 note + 1 state event into in-memory DB, call `run_explain()` with default ExplainParams, assert all 7 top-level sections present in result
    2. Write `test_explain_mr` in explain.rs: insert MR with merged_at, call `run_explain()`, assert `entity.type == "merge_request"` and merged_at is populated
    3. Write `test_explain_singular_entity_type`: call with `entity_type: "issue"`, assert it resolves same as `"issues"`
    4. Run tests — all must FAIL (red)
    5. Implement: Explain variant in Commands enum (with all flags: `--sections`, `--no-timeline`, `--max-decisions`, `--since`, singular entity type acceptance), handle_explain in handlers.rs (normalize entity_type, parse --since, build ExplainParams), skeleton `run_explain()` in explain.rs
    6. Run tests — all must PASS (green)
  - **Acceptance:** `cargo test explain::tests::test_explain_issue_basic`, `test_explain_mr`, and `test_explain_singular_entity_type` pass. Command registered in CLI help with after_help examples block.
  - **Implementation notes:**
    - Use inline args pattern (like Drift) with all flags from Code Style section
    - `entity_type` validated by `#[arg(value_parser = ["issues", "mrs", "issue", "mr"])]`
    - Normalize in handler: `"issue"` -> `"issues"`, `"mr"` -> `"mrs"`
    - Parse `--since` using `crate::core::time::parse_since()` — returns ms epoch threshold
    - Validate `--sections` values against allowed set: `["entity", "description", "key_decisions", "activity", "open_threads", "related", "timeline"]`
    - Copy the `find_issue`/`find_mr` and `get_*` query patterns from show/issue.rs and show/mr.rs — they're private functions so can't be imported
    - Use `resolve_project()` from `crate::core::project` for project resolution
    - Use `ms_to_iso()` from `crate::core::time` for timestamp conversion

### Phase 2: Core Logic

- [ ] **Task 2:** Implement key-decisions heuristic
  - **Implements:** UJ-3
  - **Files:** `src/cli/commands/explain.rs`
  - **Depends on:** Task 1
  - **Test-first:**
    1. Write `test_explain_key_decision_heuristic`: insert state change event at T, insert note by SAME author at T+30min, call `extract_key_decisions()`, assert 1 decision with correct action + context_note
    2. Write `test_explain_key_decision_ignores_unrelated_notes`: insert state change by alice, insert note by bob at T+30min, assert 0 decisions
    3. Write `test_explain_key_decision_label_event`: insert label add event + correlated note, assert decision.action starts with "label: +"
    4. Run tests — all must FAIL (red)
    4. Write `test_explain_max_decisions`: insert 5 correlated event+note pairs, call with `max_decisions: 3`, assert exactly 3 decisions returned
    5. Write `test_explain_since_scopes_events`: insert event at T-60d and event at T-10d, call with `since: Some(T-30d)`, assert only recent event appears
    6. Run tests — all must FAIL (red)
    7. Implement `extract_key_decisions()` function:
       - Query resource_state_events and resource_label_events for entity (with optional `--since` filter)
       - Merge into unified chronological list
       - For each event, find first non-system note by same actor within 60min (notes also `--since` filtered)
       - Cap at `params.max_decisions`
    8. Run tests — all must PASS (green)
  - **Acceptance:** All 5 tests pass. Heuristic correctly correlates events with explanatory notes. `--max-decisions` and `--since` respected.
  - **Implementation notes:**
    - State events query: `SELECT state, actor_username, created_at FROM resource_state_events WHERE {id_col} = ?1 AND (?2 IS NULL OR created_at >= ?2) ORDER BY created_at`
    - Label events query: `SELECT action, label_name, actor_username, created_at FROM resource_label_events WHERE {id_col} = ?1 AND (?2 IS NULL OR created_at >= ?2) ORDER BY created_at`
    - Notes query: `SELECT n.body, n.author_username, n.created_at FROM notes n JOIN discussions d ON n.discussion_id = d.id WHERE d.{id_col} = ?1 AND n.is_system = 0 AND (?2 IS NULL OR n.created_at >= ?2) ORDER BY n.created_at`
    - The `{id_col}` is either `issue_id` or `merge_request_id` based on entity_type
    - Pass `params.since` (Option<i64>) as the `?2` parameter — NULL means no filter
    - Use `crate::core::time::ms_to_iso()` for timestamp conversion in output
    - Truncate context_note to 500 chars using `crate::cli::render::truncate()` or a local helper

- [ ] **Task 3:** Implement open threads, activity summary, and cross-references
  - **Implements:** UJ-1
  - **Files:** `src/cli/commands/explain.rs`
  - **Depends on:** Task 1
  - **Test-first:**
    1. Write `test_explain_open_threads`: insert 2 discussions (1 with resolved=0 resolvable=1, 1 with resolved=1 resolvable=1), assert only unresolved appears in open_threads
    2. Write `test_explain_activity_counts`: insert 3 state events + 2 label events + 10 non-system notes, assert activity.state_changes=3, label_changes=2, notes=10
    3. Write `test_explain_no_notes`: insert issue with zero notes and zero events, assert empty key_decisions, empty open_threads, activity all zeros, description_excerpt = "(no description)" if description is NULL
    4. Run tests — all must FAIL (red)
    5. Implement:
       - `fetch_open_threads()`: query discussions WHERE resolvable=1 AND resolved=0, fetch first note author + note count per thread
       - `build_activity_summary()`: count state events, label events, non-system notes, find min/max timestamps
       - `fetch_related_entities()`: query entity_references in both directions (source and target)
       - Description excerpt: first 500 chars of description, or "(no description)" if NULL
    6. Run tests — all must PASS (green)
  - **Acceptance:** All 3 tests pass. Open threads correctly filtered. Activity counts accurate. Empty entity handled gracefully.
  - **Implementation notes:**
    - Open threads query: `SELECT d.gitlab_discussion_id, d.first_note_at, d.last_note_at FROM discussions d WHERE d.{id_col} = ?1 AND d.resolvable = 1 AND d.resolved = 0 ORDER BY d.last_note_at DESC`
    - For first note author: `SELECT author_username FROM notes WHERE discussion_id = ?1 ORDER BY created_at ASC LIMIT 1`
    - For note count: `SELECT COUNT(*) FROM notes WHERE discussion_id = ?1 AND is_system = 0`
    - Cross-references: both outgoing and incoming from entity_references table
    - For closing MRs, reuse the query pattern from show/issue.rs `get_closing_mrs()`

- [ ] **Task 4:** Wire timeline excerpt using existing pipeline
  - **Implements:** UJ-1
  - **Files:** `src/cli/commands/explain.rs`
  - **Depends on:** Task 1
  - **Test-first:**
    1. Write `test_explain_timeline_excerpt`: insert issue + state events + notes, call run_explain() with `no_timeline: false`, assert timeline_excerpt is Some and non-empty and capped at 20 events
    2. Write `test_explain_no_timeline_flag`: call run_explain() with `no_timeline: true`, assert timeline_excerpt is None
    3. Run tests — both must FAIL (red)
    4. Implement: when `!params.no_timeline` and `--sections` includes "timeline" (or is None), call `seed_timeline_direct()` with entity type + IID, then `collect_events()`, convert first 20 TimelineEvents into TimelineEventSummary structs. Otherwise set timeline_excerpt to None.
    5. Run tests — both must PASS (green)
  - **Acceptance:** Timeline excerpt present with max 20 events when enabled. Skipped entirely when `--no-timeline`. Uses existing timeline pipeline (no reimplementation).
  - **Implementation notes:**
    - Import: `use crate::timeline::seed::seed_timeline_direct;` and `use crate::timeline::collect::collect_events;`
    - `seed_timeline_direct()` takes `(conn, entity_type, iid, project_id)` — verify exact signature before implementing
    - `collect_events()` returns `Vec<TimelineEvent>` — map to simplified `TimelineEventSummary` (timestamp, event_type string, actor, summary)
    - Timeline pipeline uses `EntityRef` struct from `crate::timeline::types` — needs entity's local DB id and project_path
    - Cap at 20 events: `events.truncate(20)` after collection
    - `--no-timeline` takes precedence over `--sections timeline` (if both specified, skip timeline)

### Phase 3: Output Rendering

- [ ] **Task 5:** Robot mode JSON output and human-readable rendering
  - **Implements:** UJ-1, UJ-2
  - **Files:** `src/cli/commands/explain.rs`, `src/app/robot_docs.rs`
  - **Depends on:** Task 1, 2, 3, 4
  - **Test-first:**
    1. Write `test_explain_robot_output_shape`: call run_explain() with all sections, serialize to JSON, assert all 7 top-level keys present
    2. Write `test_explain_sections_filter_robot`: call run_explain() with `sections: Some(vec!["key_decisions", "activity"])`, serialize, assert only `entity` + `key_decisions` + `activity` keys present (entity always included), assert `description_excerpt`, `open_threads`, `related`, `timeline_excerpt` are absent
    3. Run tests — both must FAIL (red)
    4. Implement:
       - Robot mode: `print_explain_json()` wrapping ExplainResult in `{"ok": true, "data": ..., "meta": {...}}` envelope. `#[serde(skip_serializing_if = "Option::is_none")]` on optional sections handles filtering automatically.
       - Human mode: `print_explain()` with section headers, colored output, indented key decisions, truncated descriptions. Check `params.sections` before rendering each section.
       - Register in robot-docs manifest (include `--sections`, `--no-timeline`, `--max-decisions`, `--since` flags)
    5. Run tests — both must PASS (green)
  - **Acceptance:** Robot JSON matches schema. Section filtering works in both robot and human mode. Command appears in `lore robot-docs`.
  - **Implementation notes:**
    - Robot envelope: use `serde_json::json!()` with `RobotMeta` from `crate::cli::robot`
    - Human rendering: use `Theme::bold()`, `Icons`, `render::truncate()` from `crate::cli::render`
    - Follow timeline.rs rendering pattern: header with entity info -> separator line -> sections
    - Register in robot_docs.rs following the existing pattern for other commands
    - Section filtering: the `run_explain()` function should already return None for unselected sections. The serializer skips them. Human renderer checks `is_some()` before rendering.

---

## Corrections from Original Bead

The bead (bd-9lbr) was created before a codebase rearchitecture. Key corrections:

1. **`src/core/events_db.rs` does not exist** — Event storage is in `src/ingestion/storage/events.rs` (insert only). Event queries are inline in `timeline/collect.rs`. Explain needs its own inline queries.

2. **`ResourceStateEvent` / `ResourceLabelEvent` structs don't exist** — The timeline queries raw rows directly. Explain should define lightweight local structs or use tuples.

3. **`run_show_issue()` / `run_show_mr()` are private** — They live in `include!()` files inside show/mod.rs. Cannot be imported. Copy the query patterns instead.

4. **bd-2g50 blocker is CLOSED** — `IssueDetail` already has `closed_at`, `references_full`, `user_notes_count`, `confidential`. No blocker.

5. **Clap registration pattern** — The bead shows args directly on the enum variant, which is correct for explain's simple args (matches Drift, Related pattern). No need for a separate ExplainArgs struct.

6. **entity_references has no fetch query** — Only `insert_entity_reference()` and `count_references_for_source()` exist. Explain needs a new SELECT query (inline in explain.rs).

---

## Session Log

### Session 1 — 2026-03-10
- Read bead bd-9lbr thoroughly — exceptionally detailed but written before rearchitecture
- Verified infrastructure: show/ (private functions, copy patterns), timeline/ (importable pipeline), events (inline SQL, no typed structs), xref (no fetch query), discussions (resolvable/resolved confirmed in migration 028)
- Discovered bd-2g50 blocker is CLOSED — no dependency
- Decided: two positional args (`lore explain issues N`) over single query syntax
- Decided: formalize + gap-fill approach (bead is thorough, just needs updating)
- Documented 6 corrections from original bead to current codebase state
- Drafted complete spec with 5 tasks across 3 phases

### Session 1b — 2026-03-10 (CLI UX Audit)
- Audited full CLI surface (30+ commands) against explain's proposed UX
- Identified 8 improvements, user selected 6 to incorporate:
  1. **after_help examples block** — every other lore command has this, explain was missing it
  2. **--sections flag** — robot token efficiency, skip unselected sections entirely
  4. **Singular entity type tolerance** — accept `issue`/`mr` alongside `issues`/`mrs`
  5. **--no-timeline flag** — skip heaviest section for faster execution
  7. **--max-decisions N flag** — user control over key_decisions cap (default 10)
  8. **--since flag** — time-scope events/notes for long-lived entities
- Skipped: #3 (command aliases ex/narrative), #6 (#42/!99 shorthand)
- Updated: Code Style, Boundaries, Architecture (ExplainParams + ExplainResult types, section filtering, time scoping, SQL queries), Success Criteria (+5 new), Testing Strategy (+5 new tests), all 5 Tasks
- ExplainResult sections now `Option<T>` with `skip_serializing_if` for section filtering
- All sections remain complete — spec is ready for implementation