Rrr

/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.

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. 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:

• times observed, never estimated or interpolated
• attributable to this session and repository, or evidence: none
• gap-aware, so an idle overnight is not counted as session time
• beats — the minutes that actually had activity — not a start/end span
• cheap: read timestamps, not content; if it would load the conversation into context, return none instead
• degrades honestly: no source → evidence: none, and that is a correct answer

Resolve it the way your harness allows — Claude Code has a reference implementation (scripts/session-clock.py, ~50ms on a 16MB transcript); Codex should use its own rollout or session metadata; an unknown host returns none. Do not run one host's implementation against another host's layout on the assumption that it matches.

Place rows on beats. Never interpolate a time between two beats. On evidence: none, fall back to commit times, then to untimed ordered bullets.

Skip the session clock entirely under --fg.

Repository evidence is allowed in every mode. Persisted agent-session evidence is for --bg and --combo only. Commit timestamps are repository evidence, not session mining — a --fg retro may and should use them to build a real timeline.

2. Resolve artifact paths

# TZ='Asia/Bangkok' (GMT+7) was exported in step 1, so these stamps are Bangkok-local.
DATE_PATH=$(date +%Y-%m/%d)
TODAY=$(date +%Y-%m-%d)
HHMM=$(date +%H.%M)
mkdir -p "$PSI/memory/retrospectives/$DATE_PATH" "$PSI/memory/learnings"

Write:

• retrospective: $PSI/memory/retrospectives/$DATE_PATH/${HHMM}_${SLUG}.md
• lesson: $PSI/memory/learnings/${TODAY}_${SLUG}.md
• metrics: $PSI/memory/learnings/session-metrics.md

3. Execute the selected mode

Background (--bg)

Resolve every path and capability before delegation. Give one background writer the current context summary, repository evidence, normalized session evidence when available, destination paths, template requirements, and the anti-rationalization rules. Use the active host's model routing; never require a named vendor model.

Return immediately with the resolved absolute destination. If the host cannot keep work alive after returning, use the documented foreground fallback instead of pretending the task remains active.

Light (--light)

The default path with the reflective sections dropped — for a quick checkpoint mid-work where a full retro is not worth the tokens. Write only:

• header metadata (with real Start / End and Duration from the session clock)
• ## Timeline
• ## Session Summary (2–3 sentences)
• ## Lessons Learned (or an evidence-backed none)
• the metrics row

Skip Diary, What Went Well / Could Improve, Blockers, Honest Feedback, Next Steps, Related Resources, and Self-Audit. Note mode: light in the evidence line so a reader knows the reflection was intentionally omitted rather than forgotten. The silent validation gate still applies to what is written.