/rrr

name: rrr
description: Create a session retrospective with an AI diary and reusable lessons. Supports foreground, background, and combined execution across compatible agent hosts.
argument-hint: "[--fg | --bg | --combo]"

/rrr

> "Reflect to grow, document to remember."

Create a truthful session retrospective, record reusable learning, and append the session-metrics row. Never invent timestamps or claim evidence that the active host cannot provide.

Mode router

Choose one execution mode:

/rrr                              # default: foreground + session-clock timestamps
/rrr --light                      # fastest: timeline + summary + lesson only
/rrr --combo                      # foreground draft, then background evidence enrichment
/rrr --bg                         # full retrospective in the background
/rrr --fg                         # foreground, no session clock at all

`--fg`, `--bg`, and `--combo` are mutually exclusive. If more than one is supplied, stop and report the valid syntax. **When none is supplied, use the default foreground path** — synchronous, no background agent, but with real timestamps from the session clock. `--light` composes with the foreground path.

| Mode | Required behavior | |---|---| | *(none)* | **Default.** Synchronous. Real times from the host's session clock (see [HOSTS.md](HOSTS.md)) plus git commit times. No background agent; timestamps only, never conversation content. | | `--light` | The default path with only Timeline, Summary, Lesson, and Metrics. For quick checkpoints; skips Diary, Feedback, Blockers, Self-Audit. | | `--combo` | Foreground artifact now, then background mining that enriches the same file with fuller evidence. Mark enrichment pending until it completes. | | `--bg` | Mine the persisted host session and write asynchronously. Announce the destination and return without waiting. | | `--fg` | Strict: current conversation context and repository evidence only. Do not run the session clock. Do not inspect persisted session transcripts, JSONL, rollout files, or session databases. Do not launch a hidden mining agent. |

Why the default reads a session clock

A retrospective without a timeline cannot be audited. Git commit times alone leave a research or browsing session with `Duration: unknown`.

The historical fix was worse: pre-2026-08-20 retros filled the gap with **estimated** times marked `~`, back-filled from the known end time. They are recognisable by their impossible regularity — `~04:11 ~04:12 ~04:13 …`, or neat five-minute steps — because real session timestamps cluster unevenly (four events inside one minute, then nothing for twenty).

A **session clock** closes the gap without either cost. The contract asks only for observed times — read timestamps, not content — so it stays cheap on any host. Claude Code's reference implementation scans a 16MB transcript in ~50ms for a few hundred bytes of context. That is why this is the default rather than `--combo`: no background agent, no token burn, real times.

Each harness resolves the contract its own way. The skill states what it needs; it does not dictate a mechanism that only one host could satisfy.

The ban stands: never emit an estimated timestamp, with or without a tilde. If the clock reports `evidence: none` and no commits exist, say `unknown` — do not decorate the gap.

Host capability contract

Before mining or delegation, read [HOSTS.md](HOSTS.md). Detect capabilities rather than assuming Claude Code paths, Claude JSONL, a particular agent API, or a model name.

Public output should say **session mining**, not **JSONL mining**. A host adapter may internally read JSONL, rollout files, or another supported source, but it must normalize the result and preserve source attribution.

If background execution is unavailable:

• `--fg` is unaffected.
• `--bg` falls back to `--fg` and clearly reports that persisted mining was unavailable.
• `--combo` keeps the foreground artifact, marks session enrichment unavailable, and

does not fabricate a completion notification.

Oracle root detection

Run this before every `ψ/` write. Do not assume the current directory is the Oracle repo.

ORACLE_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)

if [ -n "$ORACLE_ROOT" ] && { [ -f "$ORACLE_ROOT/CLAUDE.md" ] || [ -f "$ORACLE_ROOT/AGENTS.md" ]; } \
   && { [ -d "$ORACLE_ROOT/ψ" ] || [ -L "$ORACLE_ROOT/ψ" ]; }; then
  PSI="$ORACLE_ROOT/ψ"
elif { [ -f "$(pwd)/CLAUDE.md" ] || [ -f "$(pwd)/AGENTS.md" ]; } \
   && { [ -d "$(pwd)/ψ" ] || [ -L "$(pwd)/ψ" ]; }; then
  ORACLE_ROOT="$(pwd)"
  PSI="$ORACLE_ROOT/ψ"
else
  echo "⚠️ Not in an Oracle repo. Writing under the current repository."
  ORACLE_ROOT="${ORACLE_ROOT:-$(pwd)}"
  PSI="$ORACLE_ROOT/ψ"
fi

PSI_RESOLVED=$(readlink -f "$PSI" 2>/dev/null || printf '%s' "$PSI")

Shared workflow

1. Gather repository evidence

All retro times and date-stamped paths use **GMT+7 (Asia/Bangkok)**. Pin it once so every `date` call and git timestamp below renders in GMT+7 regardless of the host's local zone:

export TZ='Asia/Bangkok'   # GMT+7 — retro timeline, header, and path stamps

Use the smallest commands that accurately describe this session:

date "+%H:%M %Z (%A %d %B %Y)"
git -C "$ORACLE_ROOT" status --short
git -C "$ORACLE_ROOT" log --oneline -10
git -C "$ORACLE_ROOT" diff --stat HEAD~5 2>/dev/null || true

# Verified commit timestamps in GMT+7. --date=format-local honors the TZ above.
git -C "$ORACLE_ROOT" log --since='18 hours ago' \
  --date=format-local:'%H:%M' --format='%ad — %s (%h)' --reverse

**Session clock — the default path's primary time source.** Ask the host for observed times. *How* is the adapter's business; **what** is fixed by the SessionClock contract in [HOSTS.md](HOSTS.md):

• [ ] times **observed**, never estimated or interpolated
• [ ] attributable to this session and repository, or `evidence: none`
• [ ] gap-aware, so an idle overnight is not counted a