docs(reflect): add ADR for session reflection mode

docs/adr/001-session-reflection-mode.md

@@ -0,0 +1,191 @@
+# ADR-001: Session Reflection Mode for /reflect
+
+**Date:** 2026-06-29
+**Status:** Accepted
+**Deciders:** User + Orchestrator
+
+## Context
+
+We are adding a `--sessions` mode to the `/reflect` command in oh-my-opencode-slim. This mode enables cross-session reflection by analyzing past OpenCode sessions to find repeated patterns, friction, and improvement opportunities.
+
+Current `/reflect` only looks at the current conversation and project files. The new mode analyzes historical sessions across all repos to find patterns like:
+- "Which workflows succeed most often?"
+- "Which agents get stuck?"
+- "Which models cause retries?"
+- "What precedes successful completions?"
+
+## Decisions
+
+### 1. Implementation Approach: Prompt-only
+
+**Decision:** Extend the reflect skill (SKILL.md) with instructions for session reflection. No new code tools or command hooks.
+
+**Rationale:**
+- Consistent with how `/reflect` currently works (prompt-based guidance)
+- The LLM already has tools (Read, Write, Bash) to do everything needed
+- Smallest useful form — no code changes required
+- YAGNI: Start simple, add code if prompt-only proves insufficient
+
+**Alternatives considered:**
+- Hybrid (skill + command hook): More reliable enumeration, but adds code complexity
+- Full code (new tool): Fastest execution, but most complex
+
+### 2. Command Syntax
+
+**Decision:** Remove `--global` (never shipped), add `--sessions` flag.
+
+```
+/reflect                          # Local mode (current repo)
+/reflect release workflow         # Local mode, focused theme
+/reflect --sessions               # Session archaeology (last 50 sessions)
+/reflect --sessions --last 20     # Session archaeology, last 20
+/reflect --sessions release workflow  # Session archaeology, focused theme
+```
+
+**Rationale:**
+- `--global` was never rolled out, so no migration needed
+- `--sessions` clearly describes the mode's purpose
+- `--last N` provides user control over scope
+
+### 3. Session Discovery
+
+**Decision:** LLM reads `~/.local/share/opencode/log/opencode.log` and greps for `session.id=ses_[a-f0-9]+` to extract session IDs.
+
+**Rationale:**
+- Session IDs are reliably present in the main OpenCode log
+- Pattern is stable and parseable with simple grep
+- No new API dependencies needed
+
+**Log format:**
+```
+timestamp=2026-06-10T15:08:45.427Z level=INFO run=9bd29194 message=loop session.id=ses_14de9c68effegtZtlATm42wnz7 step=0
+```
+
+### 4. Session Scope
+
+**Decision:** Analyze last N sessions total (regardless of project), not per-project.
+
+**Rationale:**
+- Simpler to implement
+- Patterns emerge naturally across repos
+- User controls scope with `--last N`
+- Per-project caps can be added later if needed
+
+**Default:** 50 sessions
+**Maximum:** 100 sessions (cap to avoid context explosion)
+
+### 5. Storage Location
+
+**Decision:** Store reflection summaries in `~/.config/opencode/oh-my-opencode-slim/reflections/`.
+
+**Rationale:**
+- Existing OMOS directory already contains presets, prompts, orchestrator_append.md
+- Pragmatic: keeps all OMOS data in one place
+- Easy discovery and cleanup
+- Global across projects (sessions are not project-specific)
+
+**Structure:**
+```
+~/.config/opencode/oh-my-opencode-slim/reflections/
+  sessions/
+    ses_14de9c68effegtZtlATm42wnz7.json
+  weekly/
+    week-26.json
+  monthly/
+    month-06.json
+```
+
+**Alternatives considered:**
+| Option | Pros | Cons | Decision |
+|--------|------|------|----------|
+| `~/.config/opencode/oh-my-opencode-slim/reflections/` | Existing directory, single location | Mixes config and data | **Accepted** |
+| `~/.local/share/oh-my-opencode-slim/reflections/` | XDG-compliant, data separation | New directory, splits OMOS data | Rejected |
+| `.slim/reflections/` (project-local) | Tied to codebase | Sessions are global, not project-specific | Rejected |
+| Ephemeral (no storage) | No disk overhead | Re-analyzes expensive sessions, no trend tracking | Rejected |
+
+### 6. Two-Phase Architecture
+
+**Decision:** Per-session reflection first, then aggregation.
+
+**Rationale:**
+- Scalable: processes one session at a time (not hundreds in context)
+- Aggregation works on concise summaries (20-30k tokens) not raw sessions (millions)
+- Enables hierarchical aggregation: session → weekly → monthly
+
+**Flow:**
+```
+OpenCode logs
+  → Extract session IDs
+  → For each session:
+      → Load via client.session.messages()
+      → Analyze and produce structured summary
+      → Store in reflections/sessions/<id>.json
+  → Aggregate all summaries
+  → Produce final recommendations
+```
+
+### 7. Cache Pattern
+
+**Decision:** LLM manages its own cache using Read/Write tools.
+
+**Rationale:**
+- No new code needed — LLM already has file tools
+- Avoids re-analyzing expensive sessions
+- Enables incremental updates (only analyze new sessions)
+
+**Logic:**
+1. Check if `reflections/sessions/<id>.json` exists
+2. If yes, load it (saves tokens)
+3. If no, analyze session and save summary
+4. Aggregate across all summaries for final report
+
+### 8. Per-Session Analysis
+
+**Decision:** Each session produces a structured JSON summary with metadata, frictions, and recommendations.
+
+**Schema:**
+```json
+{
+  "session": "ses_14de9c68effegtZtlATm42wnz7",
+  "project": "/home/user/Projects/oh-my-opencode-slim",
+  "timestamp": "2026-06-10T15:08:45.427Z",
+  "goal": "Fix CI failure",
+  "success": true,
+  "frictions": [
+    "Repeated grep to find test file",
+    "Three failed test runs before passing"
+  ],
+  "recommendations": [
+    "Create /test-ci command"
+  ],
+  "duration_minutes": 18,
+  "models_used": ["opencode/mimo-v2.5-free"],
+  "agents_used": ["orchestrator", "fixer", "explorer"],
+  "tools_used": ["Read", "Edit", "Bash"],
+  "confidence": 0.85
+}
+```
+
+**Confidence scoring:**
+- 0.9-1.0: Clear success/failure, obvious patterns
+- 0.7-0.9: Likely outcome, patterns inferred from tool usage
+- 0.5-0.7: Uncertain outcome, limited evidence
+- <0.5: Skip or mark as "needs more evidence"
+
+## Implementation Notes
+
+- The LLM manages its own cache using Read/Write tools
+- Reflection files are JSON with session metadata, frictions, and recommendations
+- Hierarchical aggregation: session → weekly → monthly summaries
+- Old reflections can be pruned by age or count (configurable)
+- Skill instructions guide the LLM through the full workflow
+
+## Consequences
+
+- No code changes needed — purely skill instruction updates
+- All OMOS persistent data lives in one directory tree
+- Reflections are available across all projects (global)
+- LLM manages file I/O, cache, and aggregation
+- Users can inspect or delete reflections manually
+- Hierarchical aggregation (weekly/monthly) is possible via stored summaries
+- Per-project session caps can be added later if needed