ruminate

Files (2)

• SKILL.md
• extract-conversations.py · scripts/

SKILL.md (first lines)

# Ruminate

Mine conversation history for brain-worthy knowledge that was never captured. Complements `reflect` (current session) and `meditate` (brain vault audit) by looking at the full archive of past conversations across available providers.

## Process

Track each step through the available planning tools or a short checklist.

### 1. Read the brain

Build a brain snapshot: `sh .agents/skills/meditate/scripts/snapshot.sh brain/ /tmp/brain-snapshot-ruminate.md`. Pass the snapshot path to each analysis agent. This avoids loading the full brain into the ruminate orchestrator's context.

### 2. Locate conversations

Find both provider roots:

1. Claude project directory:
   `~/.claude/projects/-<cwd-with-dashes-replacing-slashes>/`
2. Codex sessions root:
   `~/.codex/sessions/`
3. Copilot sessions root:
   `~/.copilot/`

### 3. Extract conversations

Run the extraction script to parse both JSONL formats into readable text and split into batches:

```bash
SKILL_DIR="$(dirname "$(realpath "$0")")/.."  # adjust path as needed
CLAUDE_DIR="$HOME/.claude/projects/-<project-slug>"
CODEX_DIR="$HOME/.codex/sessions"
COPILOT_DIR="$HOME/.copilot"
OUT_DIR="/tmp/ruminate-$(date +%s)"

python3 "$SKILL_DIR/scripts/extract-conversations.py" "$OUT_DIR" \
  --claude-dir "$CLAUDE_DIR" \
  --codex-dir "$CODEX_DIR" \
  --copilot-dir "$COPILOT_DIR" \
  --cwd "$PWD" \
  --batches N
```

Choose N based on total extracted conversations (Claude + Codex + Copilot): ~1 batch per 20 conversations, minimum 2, maximum 10.

### 4. Spawn analysis team

Analyze each batch with available general analysis subagents, following the model-routing skill when available and respecting harness concurrency limits. Use bounded local passes if delegation is unavailable.

Each agent's prompt should include:

- The batch manifest path (`$OUT_DIR/batches/batch_N.txt`)
- The output path (`$OUT_DIR/findings_N.md`)
- The list of topics **already captured** in the brain (compiled from step 1) - so agents skip known knowledge
- A reminder that each extracted file includes provider/source metadata headers (`[PROVIDER]`, `[CWD]`, `[SOURCE_FILE]`) and should be used as evidence context
- Instructions to extract from each conversation:
  - **User corrections**: times the user corrected the assistant's approach, code, or understanding
  - **Recurring preferences**: things the user explicitly asked for or pushed back on repeatedly
  - **Technical learnings**: codebase-specific knowledge, gotchas, patterns discovered
  - **Workflow patterns**: how the user prefers to work
  - **Frustrations**: friction points, wasted effort, things that went wrong
  - **Skills wished for**: capabilities the user expressed wanting

Agents write structured findings to their output files.

### 5. Synthesize

After all agents complete, read all findings files. Cross-reference with existing brain content. Deduplicate across batches.

**Filter by frequency and impact.** Most findings won't be worth adding. Apply these filters before presenting:

- **Frequency**: Did this come up in multiple conversations, or was the user correcting the same mistake repeatedly? One-off corrections are usually not worth a brain entry - the brain should capture _patterns_, not incidents.
- **Factual accuracy**: Is something in the brain now wrong? (e.g. a rule was disabled but the brain still documents it as active). These are always worth fixing regardless of frequency.
- **Impact**: Would failing to capture this cause repeated wasted effort in future sessions? A gotcha that cost 5 minutes once is low-impact. A pattern that caused 3 rounds of corrections is high-impact.

**Discard aggressively.** It's better to present 3 high-signal findings than 9 that include noise. If a finding only happened once and isn't a factual correction, skip it.

### 6. Present and apply

Present findings to the user in a table with columns: finding, frequency/evidence, and proposed action. Be honest about which findings are one-offs vs. recurring patterns - let the user decide what's worth adding.

**Route skill-specific learnings.** Check if any findings are about how a specific skill should work - its process, prompts, edge cases, or troubleshooting. Update the skill's SKILL.md or references/ directly. Read the skill first to avoid duplicating or contradicting existing content.

Apply only the changes the user approves. Follow brain writing conventions:

- One topic per file, organized in directories
- Use file-relative Markdown links to connect related notes
- Maintain curated indexes through the brain skill and let hooks reconcile the root inventory
- Default to updating existing notes over creating new ones

### 7. Clean up

Remove the temporary extraction directory:

```bash
rm -rf "$OUT_DIR"
```

## Guidelines

- **Filter aggressively.** Most conversations will have low signal - automated tasks, trivial exchanges, already-captured knowledge. Only surface what's genuinely new and impactful.
- **Prefer reduction.** If a finding is a special case of an existing brain principle, update the existing note rather than creating a new one.
- **Quote the user.** When a finding stems from a direct user correction, include the user's words and source file path - they carry the most signal about what matters.
- **Shut down agents** when analysis is complete. Don't leave them idle.

From japurcell/skills, MIT.

More from japurcell/skills