oh-my-opencode-slim/docs/adr/001-session-reflection-mode.md

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:

{
  "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