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

Foreground (--fg)

Write the artifact synchronously using current conversation context and repository evidence only. Build the Timeline from the verified GMT+7 commit timestamps gathered in step 1 — real HH:MM rows, not unknown. Set the header Start / End to the first and last commit time (or the current clock when there are no commits this session), and Duration to their span. Only events with no timestamped evidence at all fall back to ordered untimed bullets. State Persisted session mining: disabled by --fg in the evidence note.

Combined (--combo)

First write a complete, useful context-based retrospective synchronously. Its Timeline may contain ordered untimed entries and must include Session enrichment: pending. Then launch one background miner/writer using the host adapter. It updates the same file atomically: merge verified timestamps/evidence, replace the pending marker with the source and completion status, and preserve user edits made after the initial write.

Use --combo when you want more than times — full transcript evidence, quoted decisions, tool-level detail. For times alone the default path is faster and cheaper. If the host cannot mine, replace the pending marker with session enrichment unavailable and leave the timeline as the session clock produced it — never fill it with estimates.

4. Retrospective content

Use TEMPLATE.md for every mode. It preserves the detailed retrospective shape: session metadata, summary, timeline, technical details, key changes, architecture decisions, AI Diary, wins, improvements, blockers, Honest Feedback, lessons, next steps, related resources, and Self-Audit — the written retro ends at Self-Audit.

Before saving, silently verify the retro against TEMPLATE.md's validation gate. It is an internal quality check — run it, fix what fails, and never write the checklist into the retrospective file.

Small sessions may have short sections or an evidence-backed none; they must not drop required reflection sections, and must still pass the silent validation gate.

5. Timeline rules

1. Never invent timestamps. A tilde does not license a guess — ~04:12 is a fabricated timestamp wearing a disclaimer. Evenly spaced rows (every 1 or 5 minutes) are the signature of back-filling from the end time; real ones cluster unevenly.
2. All times render in GMT+7 (Asia/Bangkok) — the TZ exported in step 1 covers date and git --date=format-local alike. Label rows plainly as HH:MM (GMT+7).
3. Prefer verified times from these sources, in order: session clock beats (host adapter, default path) → normalized session evidence (--bg/--combo) → git commit timestamps (any mode) → the current clock for the closing entry. Never interpolate a row time between two beats.
4. Same-day sessions show the date once and HH:MM in rows.
5. Multi-day sessions group rows under ### YYYY-MM-DD.
6. Only fall back to ordered untimed bullets when NO timestamped evidence exists at all — not merely because session mining is off. If any commit landed this session, the timeline has real times.
7. Record the evidence source: session-clock, Claude adapter, Codex adapter, git-commit-times, context-only, or unknown.

6. Lesson and metrics

Write a lesson only when it transfers to another project:

---
pattern: <generalizable lesson in one line>
date: <today>
source: rrr: <repo>
concepts: [<tags>]
---

Create the metrics file when absent:

# Oracle Session Metrics

| when | session | done | stuck | win | friction | error |
|---|---|---|---|---|---|---|

Append exactly one row for every run. Use unknown when the host cannot provide a session ID. Never skip a trivial session; record trivial where appropriate.

Review the last seven metrics rows. If a theme appears at least three times in either friction or error, surface a recurring-pattern section in the retrospective. Do not open an issue automatically.

7. Save and announce

Do not git add ψ/; it may resolve to a shared vault.

Announce absolute paths only:

📝 Retrospective:  <absolute path>
💡 Lesson learned: <absolute path, or "not created — no generalizable lesson">
📊 Metrics row:    <absolute path>

Rules

• Default execution mode is --fg.
• --fg never mines persisted session data and never launches a hidden miner.
• --bg and --combo are the only modes allowed to mine persisted session data.
• --combo is the only foreground-plus-background-enrichment mode.
• Never hard-code Claude storage, JSONL schema, agent APIs, team APIs, or model names in the shared flow; isolate host details in HOSTS.md.
• Never invent timestamps, session IDs, commits, files, or completed background work.
• Do not create coordinated teams or multi-agent analysis trees for /rrr.
• Keep vault writes outside git staging.