/oma-recap

name: oma-recap
description: Summarize AI conversation histories for a specified date or period.
  Use for daily work recaps and cross-tool activity summaries.

AI Tool Conversation History Summary

Analyze AI tool conversation histories for a given period and generate themed work summaries.

Scheduling

Goal

Collect AI tool conversation history for a date or window and synthesize it into a themed, project-oriented recap with saved Markdown output.

Intent signature

• User asks for daily recap, weekly/monthly summary, standup notes, work log, tool usage pattern, or AI conversation history analysis.
• User wants conversation histories grouped by work content rather than raw chronological logs.

When to use

• Summarizing a day or period of work activity
• Understanding the overall flow of work across multiple AI tools
• Analyzing tool-switching patterns between sessions
• Preparing daily standups, weekly retros, or work logs

When NOT to use

• Git commit-based code change retrospective -> use `oma retro`
• Real-time agent monitoring -> use `oma dashboard terminal`
• Productivity metrics -> use `oma stats get`

Expected inputs

• Date, relative date, time window, or tool filter
• Conversation history available through `oma recap --json` or fallback sources
• Desired daily or multi-day recap scope

Expected outputs

• Markdown recap saved to `.agents/results/recap/{date}.md` or range filename
• TL;DR, overview, themes/projects, miscellaneous or side projects, and tool usage patterns
• User-facing summary in configured response language

Dependencies

• `oma recap --json`
• Optional Claude fallback history at `~/.claude/history.jsonl`
• `.agents/oma-config.yaml` for language behavior

Control-flow features

• Branches by date resolution, window length, available tool history, and daily vs multi-day output shape
• Reads local history data and writes Markdown recap files
• Groups by content, not by tool

Structural Flow

Entry

1. Resolve requested date or window. 2. Collect normalized conversation history. 3. Decide daily versus multi-day output structure.

Scenes

1. **PREPARE**: Resolve time range and tool filters. 2. **ACQUIRE**: Collect history through CLI or fallback; retain completion evidence where available. 3. **REASON**: Group by content and classify each item as requested, in progress, or completed from its evidence. 4. **ACT**: Write recap Markdown in the required format. 5. **VERIFY**: Check that every completion claim has direct evidence, then check grouping, language, and output path. 6. **FINALIZE**: Save and display summary.

Transitions

• If no date is specified, use today via `--date` (bare `--window` is a rolling window ending now, not calendar-aligned).
• If window is 3 days or longer, group by project instead of day chronology.
• If CLI is unavailable, use Claude fallback only and report scope limits.
• If tasks are under threshold, group them into Miscellaneous or Side Projects.

Failure and recovery

• If history is unavailable, report missing source and requested range.
• If timestamps are ambiguous, use configured timezone and state assumption.
• If extracted data is sparse, produce a concise recap and note limited coverage.

Exit

• Success: recap file exists and summary is displayed.
• Partial success: missing tools/history or fallback-only coverage is explicit.

Logical Operations

Actions

| Action | SSL primitive | Evidence | |--------|---------------|----------| | Resolve date/window | `INFER` | Natural-language date rules | | Collect history | `CALL_TOOL` | `oma recap --json` or `jq` fallback | | Read extracted records | `READ` | Conversation history | | Group and classify themes/projects | `INFER` | Time/content rules plus prompt, progress, completion, receipt, or artifact evidence | | Validate output shape | `VALIDATE` | Daily or multi-day template | | Write recap | `WRITE` | `.agents/results/recap/` | | Report summary | `NOTIFY` | Displayed recap |

Tools and instruments

• `oma recap --json`
• `jq` fallback for Claude history
• Markdown output templates

Canonical command path

oma recap --date YYYY-MM-DD --json
oma recap --window 7d --json
oma recap --json  # rolling last 24h, not "today"

Resource scope

| Scope | Resource target | |-------|-----------------| | `LOCAL_FS` | Conversation history and recap output files | | `PROCESS` | `oma recap`, `jq`, date commands | | `USER_DATA` | Conversation prompts and project activity | | `MEMORY` | Theme grouping and summary notes |

Preconditions

• Requested time range can be resolved.
• At least one history source is available.

Effects and side effects

• Writes recap Markdown under `.agents/results/recap/`.
• Reads local conversation history data.

Guardrails

1. **Evidence status**: A prompt alone proves a request, not a result. Mark work **completed** only with an explicit completion/result message, a receipt, or an artifact that supports the stated outcome. Mark it **in progress** with progress evidence; otherwise call it **requested**. Do not infer completion from a tool invocation or elapsed time. 2. **TL;DR required**: Top 3 supported outcomes. Use "completed" only when the evidence-status rule permits it; otherwise summarize requested or in-progress work plainly. Project name + status/outcome. No tool names or unnecessary detail. 3. **Overview**: After TL;DR, describe the flow. Start with "I" as subject and preserve evidence status. 4. **Daily**: themes by time block (15+ min). Rest goes to "Miscellaneous". 5. **Multi-day (3d+)**: sections by project, ordered by activity. Read like a sprint report, not a daily log. 6. **2-4 bullets per theme/project**: Concise essentials only. Don't enumerate every step. 7. **Themes by content**: Group by actual work, not by tool. 8. **Time range (daily only)**: `(AM/PM/Evening HH:MM~HH:MM)`. AM: ~12:00, PM: 12:00~18:00, Evening: 18:00~. 9. **Save results**: Write markdown t