rrr

Files (4)

• HOSTS.md
• SKILL.md
• TEMPLATE.md
• session-clock.py · scripts/

SKILL.md (first lines)

# /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:

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

```bash
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:

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

Use the smallest commands that accurately describe this session:

```bash
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
```

From Soul-Brews-Studio/arra-oracle-skills-cli, MIT.

More from Soul-Brews-Studio/arra-oracle-skills-cli