Reflect

Reflect is an orchestrator-only workflow for learning from repeated work. It looks back over recent sessions, project notes, and existing agent assets, then recommends the smallest useful improvement: a skill, custom agent, command, configuration change, prompt rule, documentation playbook, or no change.

The goal is to identify real repeated friction and suggest practical improvements with evidence.

Branch: lines marked [branch: --sessions] run only with that flag; plain /reflect skips Session Mode.

When to Use

Use Reflect when the user asks to:

• run /reflect or /reflect <focus>;
• run /reflect --sessions for session archaeology;
• learn from recent sessions or repeated workflows;
• find work they keep doing manually;
• improve their oh-my-opencode-slim setup based on actual usage using oh-my-opencode-slim skill;
• review whether a recurring process should become a reusable playbook;
• turn repeated workflow friction into a safer future default.

Do not use Reflect for ordinary implementation work, one-off debugging, broad architecture review, or speculative agent creation without workflow evidence.

Session Mode [branch: --sessions]

When the user includes --sessions in their reflect command, shift to session archaeology: analyze historical OpenCode sessions across all repos to find repeated patterns, friction, and improvement opportunities.

Session Discovery

1. Detect the schema, then load recent sessions. OpenCode v2 keeps live data in session_v2 + session_message; legacy v1 databases keep session

   • message (on v2 hosts those may still exist but are empty leftovers). Detect by probing session_v2 in sqlite_master and select the pair together — never per-table: session_message can exist on v1 hosts holding only metadata rows.

   Write the probe below to a temp file (for example /tmp/reflect-sessions.mjs) and run bun /tmp/reflect-sessions.mjs. Do not inline it with bun -e "…": nested quotes get mangled by PowerShell on Windows; a temp script sidesteps shell quoting entirely.

   import Database from 'bun:sqlite';
   import { homedir } from 'os';
   const db = new Database(`${homedir()}/.local/share/opencode/opencode.db`, { readonly: true });
   const isV2 = !!db.query("SELECT 1 FROM sqlite_master WHERE type='table' AND name='session_v2'").get();
   const LIMIT = 50; // set to the --last N value when specified
   const sessions = isV2
     ? db.query(
         `SELECT s.id, p.worktree AS project, s.title, s.agent, s.model, s.time_created, s.cost, s.tokens_input, s.tokens_output, s.time_archived FROM session_v2 s LEFT JOIN project p ON p.id = s.project_id ORDER BY s.time_created DESC LIMIT ${LIMIT}`
       ).all()
     : db.query(
         `SELECT id, directory AS project, title, agent, model, time_created, cost, tokens_input, tokens_output FROM session ORDER BY time_created DESC LIMIT ${LIMIT}`
       ).all();
   console.log(sessions);

   Both branches emit a project path for the Per-Session Analysis. Timestamps are epoch milliseconds. On v2, a non-null time_archived means the session was archived inside OpenCode.

2. Load session messages - for each session ID, query the matching message table and parse data:

   const rows = isV2
     ? db.prepare('SELECT type, seq, data FROM session_message WHERE session_id = ? ORDER BY seq').all('<session_id>')
     : db.prepare('SELECT data FROM message WHERE session_id = ?').all('<session_id>');

   v2 rows carry a type column — parse data JSON by it:

   • user → data.text
   • assistant → join data.content[] entries where entry.type === 'text' (use .text)
   • summary → data.summary (compaction summaries; useful for reconstructing goals)
   • tool types → keep the tool name for tools_used (plus any error/failure signal), skip the output payload; reasoning types → skip entirely

   v1 rows have no type column — data is JSON with role, agent, model, summary, etc.

Per-Session Analysis

For each session, analyze and produce a structured summary:

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

Storage and Caching

Store session summaries in ~/.config/opencode/oh-my-opencode-slim/reflections/sessions/.

Cache logic:

1. Check if <session-id>.json exists in reflections directory
2. If yes, load it (saves tokens)
3. If no, analyze session and save summary
4. Aggregate across all summaries for final report

Aggregation

After analyzing all sessions, aggregate findings:

1. Group by theme - sessions with similar frictions cluster together
2. Count frequency - "42/50 sessions had repeated grep before editing"
3. Rank by impact - prioritize recommendations that appear most often
4. Filter noise - skip one-off issues, focus on repeated patterns
5. Cross-reference - see if patterns correlate with specific models, agents, or repos

Scope categories:

• Global - applies to all repos (pattern seen in >50% of repos)
• Cross-repo - applies to specific repos where pattern appears
• Project-specific - only relevant to one repo

Output Format

Return a compact report with scope and confidence:

Session Reflection Report
Analyzing 50 most recent sessions across 8 repos.

Repos analyzed:
- <repo> (<N> sessions)
- ... (M more)

Findings
- <pattern>: N/50 sessions across M repos.
  - Scope: global | cross-repo (<repos>) | project-specific (<repo>)
  - Confidence: 0.95
  - Impact: High | Medium | Low

Recommended changes
- <asset>: <purpose>
  - Scope: global | cross-repo (<repos>) | project-specific (<repo>)
  - Confidence: 0.97
  - Estimated time saved: High | Medium | Low

Skipped
- <candidate>: why not worth packaging now.
  - Scope: <reason>
  - Confidence: <score>

Needs more evidence
- <candidate>: what would make it actionable.
  - Current scope: <what we've seen>
  - Required scope: <what would confirm>

Error Handling

Log file issues:

• Log doesn't exist → "No OpenCode log found at . Run OpenCode in at least one repo first."
• Log is empty → "OpenCode log is empty. No sessions to analyze."

Session loading issues:

• Session ID not loadable → Skip with warning: "Session could not be loaded, skipping."
• Session has no messages → Skip: "Session has no messages."

Recovery pattern:

• Log the failure
• Continue with remaining sessions
• Report failures at end: "3 sessions skipped due to load errors"

Core Contract

Reflect must be conservative and evidence-driven.

Required behavior:

• inspect existing assets before suggesting new ones;
• prefer recent, repeated, user-visible friction over isolated incidents;
• recommend the smallest useful form;
• treat "create nothing" as a successful result when evidence is weak;
• ask before changing prompts, skills, commands, agents, MCP access, or config;
• avoid duplicating existing assets;
• explain restart requirements for OpenCode config, prompt, agent, skill, MCP, or plugin changes.

Evidence Sources

Use available evidence in this order:

1. Current conversation and explicit user instructions.
2. Project-local guidance and memories, such as AGENTS.md, .opencode/, .slim/, notes, checkpoints, task progress files, and codemaps.
3. Existing skills, commands, agents, prompt overrides, MCP permissions, and oh-my-opencode-slim configuration.
4. Recent OpenCode logs or session artifacts if they are available and safe to inspect.
5. External docs only when a proposed workflow depends on a third-party tool or library whose behavior needs confirmation.

Respect privacy and safety boundaries. Do not inspect unrelated personal files, credentials, private messages, or external accounts unless the user explicitly asks and the workflow requires it.

Workflow

Reflect can be triggered directly:

/reflect
/reflect release workflow and checks
/reflect --sessions
/reflect --sessions --last 100

With no arguments, review recent work broadly. With arguments, focus the review on that workflow area while still checking whether existing assets already cover it.

1. Inventory Existing Assets

Before proposing anything, identify what already exists:

• bundled and user-installed skills;
• custom agents and their orchestratorPrompt guidance;
• custom commands;
• prompt overrides and append files;
• active oh-my-opencode-slim preset, model routing, skills, and MCP permissions;
• project playbooks, docs, codemaps, and local workflow notes.

If an existing asset already covers the candidate, recommend extending or using that asset instead of creating a near-duplicate.

2. Find Repeated Workflow Patterns

Look for repeated signals such as:

• the same command sequence appears across sessions;
• the user repeatedly asks for the same review, setup, release, or debugging process;
• the same manual research or context-gathering steps keep recurring;
• the same specialist routing decision is repeatedly needed;
• the same project-specific rule is repeatedly re-explained;
• repeated failures happen because an agent lacks a stable instruction, tool, or permission boundary.

Strong candidates usually have at least two occurrences, stable inputs, a clear output, and a clear stopping condition.

3. Score Candidates

For each candidate, decide:

• Frequency: How often has it happened?
• Cost: Does it waste meaningful time, context, money, or attention?
• Risk: Does inconsistent execution cause bugs, regressions, bad decisions, or unsafe changes?
• Stability: Are the inputs and desired output predictable?
• Coverage: Is there already an asset that handles it well?

Only recommend creating or changing assets when confidence is high.

4. Choose the Smallest Useful Form

Pick the least powerful form that solves the repeated problem:

• Prompt/config rule: a small behavior change to an existing agent.
• Skill: reusable workflow guidance for a task shape.
• Command: a repeatable manual trigger with stable inputs.
• Custom agent: a distinct specialist lane with clear delegation rules.
• MCP/tool permission change: a safe access adjustment for an existing agent.
• Project playbook/doc: human-readable process guidance when automation is too heavy.
• Skip: weak, one-off, ambiguous, sensitive, or already-covered work.

Avoid creating custom agents when a prompt rule or skill is enough. Avoid skills when a short project playbook is enough. Avoid config changes when the benefit is unclear.

5. Propose Before Changing

Unless the user explicitly requested a specific edit, present a concise proposal before writing files or changing config:

Found 2 strong repeated workflows and 1 weak candidate.

Recommended:
- Add a small orchestrator prompt rule for <workflow> because <evidence>.
- Extend existing <skill> instead of creating a new one because <overlap>.

Skip:
- <candidate> because it only appeared once.

Proceed with the proposed edits?

When applying changes, preserve existing user settings and prefer narrow, append-only edits.

Output Format

Return a compact report:

Findings
- <workflow>: evidence, frequency/confidence, recommended form.

Recommended changes
- <asset/config/doc>: one-line purpose and why this is the smallest useful form.

Skipped
- <candidate>: why not worth packaging now.

Needs more evidence
- <candidate>: what would make it actionable.

If nothing qualifies, say:

No strong repeated workflow found. I would not add or change any reusable assets
yet.

Guardrails

• Do not manufacture assets to justify the workflow.
• Do not create overlapping skills or agents.
• Do not silently change global config, prompts, or permissions.
• Do not add broad instructions that make agents more eager, expensive, or invasive without a clear benefit.
• Do not overfit to a single session unless the user explicitly asks for that exact reusable workflow.
• Do not use private or sensitive material as examples in generated assets.
• When config, prompt, agent, skill, MCP, or plugin files change, tell the user: "This should apply on the next OpenCode run; restart OpenCode if you need it immediately."