---
name: sync-claude-sessions
description: >
  Scan recent Claude session transcripts for high-signal user corrections,
  then analyze them into candidate RULES / SKILL suggestions / recurring patterns
  as input for improve-system. NEVER auto-applies anything.
triggers:
  - /sync-claude-sessions
  - /sync-sessions
---

# sync-claude-sessions

Surfaces correction signals buried in `.jsonl` session transcripts and turns
them into actionable improve-system candidates — without touching CLAUDE.md
or any skill files directly.

---

## Procedure

### Step 1 — Run the scanner

```bash
python3 ~/.claude/skills/sync-claude-sessions/scripts/scan.py
```

The script:
- Reads the watermark at `~/.claude/improve/sessions/processed.json`
- Finds `~/.claude/projects/*/*.jsonl` files **modified since last run**
- Streams each file line-by-line (never loads whole file into memory)
- Detects user turns matching correction patterns ("no, do X", "you missed",
  "I keep asking", "remember:", "stop asking", "wrong", etc.)
- Writes a dated digest to `~/.claude/improve/sessions/YYYY-MM-DD-candidates.md`
- Updates the watermark with new mtimes

> If "No new or modified .jsonl files since last run." — nothing to do;
> report that and stop.

### Step 2 — Read the digest

Open the digest file the script just printed (e.g.
`~/.claude/improve/sessions/2026-06-29-candidates.md`) and read every signal
under `### Raw correction signals`.

### Step 3 — Classify and draft candidates

For each signal, classify it as one of:

| Class | Meaning |
|-------|---------|
| **RULE** | A hard behavioural rule that belongs in CLAUDE.md |
| **SKILL** | A multi-step procedure worth its own skill file |
| **PATTERN** | A recurring mistake — note it but it may not yet justify a rule |
| **NOISE** | System injection, one-off, or already covered — skip |

For RULE and SKILL candidates write:
```
**Class:** RULE | SKILL
**Draft text:** [one-sentence rule or skill name + description]
**Evidence:** > "[quoted fragment from the signal]"
**Existing coverage:** [name the CLAUDE.md section or skill that already
  covers this, if any — mark "none" if genuinely new]
**Recommendation:** Add / Strengthen existing / Skip
```

For PATTERN candidates write a one-liner noting the recurring behaviour and
how many signals exhibit it.

### Step 4 — Append analysis to the digest

Append the following section to the **same** dated `candidates.md` file:

```markdown
## Analyzed candidates
_Analyzed by Claude on <ISO timestamp>_

### RULE candidates
<drafted rules>

### SKILL candidates
<drafted skills>

### PATTERNS
<recurring patterns>

### Skipped (noise / already covered)
<list>
```

Use `>>` append — never overwrite the scan section above it.

### Step 5 — Report to Andrew

Surface the **top 3 highest-value candidates** inline (one line each), then
give the path to the full digest for review.

---

## Hard constraints

- **NEVER modify CLAUDE.md, any skill file, or any memory file.** This skill
  is read-and-draft only; every output is input for improve-system.
- **NEVER auto-apply a rule or create a new skill.** Andrew reviews and
  decides; this skill surfaces candidates, nothing more.
- If the digest exceeds ~200 KB the scanner caps output automatically;
  note "cap reached" in the report.

---

## Files touched

| File | Access |
|------|--------|
| `~/.claude/improve/sessions/processed.json` | read + write (watermark) |
| `~/.claude/improve/sessions/YYYY-MM-DD-candidates.md` | append |
| `~/.claude/projects/*/*.jsonl` | read-only stream |
