---
name: improve-system
description: Scheduled improvement ENGINE for the Claude collaboration system. Reads session logs, memory files, metrics, and promotion-queue candidates since last run; proposes auto-approved fixes inline and queues higher-stakes changes for Andrew's sign-off. Runs Tue+Fri PM after sync-claude-sessions, or interactively via /improve-system.
---

# improve-system — scheduled collaboration-system maintenance

This skill keeps the collaboration system (CLAUDE.md, memory files, skills, rules) accurate and
fresh without requiring Andrew's attention for low-risk housekeeping. It auto-applies safe fixes
immediately and writes a single consolidated review file for anything that needs a human decision.

It is the complement of `revisit`, not its replacement. `revisit` handles per-session retrospectives
run at the end of a live session. `improve-system` handles ingestion-derived findings and
cross-project systemic improvements surfaced after the fact — from session logs, metrics, newly-added
memory files, and the sync pipeline.

---

## Procedure

### Step 1 — Gather inputs since last run

Determine the last-run date from the newest entry in `~/.claude/improve/changelog.md`. Collect:

1. **Session logs** — every `conversations/YYYY-MM-DD*.md` in `~/projects/*/conversations/` (and
   `~/.claude/` itself) modified after the last-run date. Skim for mistakes, corrections, new rules,
   and "I should do X differently" notes.

2. **Per-project metrics** — `~/projects/*/conversations/metrics.md`. Note any metric that has
   trended below target for 2+ consecutive sessions (first-attempt accuracy < 90%, autonomy < 90%,
   round-trips > 1).

3. **Memory files** — list `~/.claude/projects/-Users-accunliffe/memory/` for files added or
   modified since last run. Check whether each is indexed in `MEMORY.md`; note missing entries.

4. **Sync-pipeline output** — read the latest `~/.claude/improve/sessions/YYYY-MM-DD-candidates.md`
   digest (the `## Analyzed candidates` section) emitted by sync-claude-sessions. Ingest the
   classified RULE / SKILL / PATTERN items. (`processed.json` in that dir is only the scan watermark —
   not a findings source.)

5. **Promotion queue** — read `conversations/PROMOTION-QUEUE.md` in any project that has one; ingest
   items not yet marked done.

Skip any input source that doesn't exist — do not error.

---

### Step 1b — Loop-opportunity scanner

While reading the Step-1 session logs, also scan for **recurring wait-shapes** — signals that a
manual, repeated, or polling behaviour should become a /loop, a schedule, or a skill:

- **Polling language:** "is it done yet", "what's taking so long", "still waiting on", "check again",
  repeated status checks of the same external state (deploys, TestFlight processing, CI, queues).
- **Repeated manual sequences:** the same multi-step procedure hand-run in 2+ sessions
  (build→upload→poll, capture→crop→compare, export→convert→place).
- **Missed loop triggers:** a deploy/build-upload/overnight-grind moment where the standing
  /loop triggers in CLAUDE.md ("Standing /loop triggers") should have fired but didn't.

For each hit, propose ONE candidate into the normal review queue (Step 3, NEED-SIGNOFF —
these change future agent behaviour, so they are never auto-applied):
- **loop candidate** — recurring in-session wait → proposed /loop prompt + cadence + exit condition.
- **schedule candidate** — recurring cross-session task → proposed cloud routine or launchd job.
- **skill candidate** — recurring manual sequence → proposed skill name + trigger + 3-line outline.

Cite the evidence (log file + quote) per candidate. Dedupe against candidates already
proposed in earlier review files (grep ~/.claude/improve/review/) — re-proposing a rejected
candidate needs NEW evidence since the rejection.

---

### Step 2 — Propose improvements; triage into 3 buckets

Andrew's appetite is **lean autonomous** (2026-06-29): auto-apply housekeeping AND low-risk
*additive* content; only genuinely risky or ambiguous changes wait for sign-off. Apply the hard
constraint first, then bias toward acting on what's clearly safe.

> **HARD CONSTRAINT — these are ALWAYS NEED-SIGNOFF, never AUTO-APPROVE (no exceptions):**
> - Any edit to a skill file (`~/.claude/skills/**`)
> - Any edit to CLAUDE.md (`~/.claude/CLAUDE.md`)
> - **Editing or deleting an EXISTING memory file** (changing/removing a fact already recorded)
> - Promoting a finding to a permanent global behaviour rule (those live in CLAUDE.md → sign-off)
> - Any change that alters how the agent behaves on a future task, or that *contradicts* an existing memory/rule

The line: **add new additive fact** = can be lean-autonomous; **edit/delete/override existing, or
touch a loaded surface (CLAUDE.md / skills)** = always sign-off. After that check, triage:

**AUTO-APPROVE** — low risk, additive, doesn't change existing behaviour:
- Dead `[[memory-link]]` references in CLAUDE.md or memory files (link target no longer exists)
- Missing or drifted `MEMORY.md` index entries (file exists, index line absent or stale)
- Stale relative-date phrases in memory files (`"last week"`, `"recently"`, `"2 days ago"`) that
  can be resolved to an absolute date from the log timestamps
- Obvious typos in memory files or `~/.claude/improve/changelog.md` itself
- Whitespace / formatting drift in files the skill owns
- **Creating a NEW additive memory file** (+ its `MEMORY.md` index line) when ALL of:
  (a) the fact was **explicitly stated by Andrew** OR is a **clearly repeated pattern (3+ occurrences)**
  in the inputs; (b) it is **additive** — does not contradict, edit, or override any existing memory or
  rule; (c) it is a *fact/preference/reference*, not a new global behaviour rule (those still need
  CLAUDE.md sign-off). Write it with correct frontmatter + cross-links.
- **Small, non-behavioural doc tweaks** to files the skill owns (`~/.claude/improve/*`, non-canonical
  `~/.claude/kb/*` notes): clarifying a sentence, fixing a path, updating a date.

When unsure whether something is additive-and-safe vs behaviour-changing, treat it as NEED-SIGNOFF.
Lean ≠ reckless: a wrong auto-apply to a loaded surface is costly; one extra sign-off item is one checkbox.

For each AUTO-APPROVE item: **apply the fix immediately**, then append one line to
`~/.claude/improve/changelog.md`:
```
- YYYY-MM-DD | <what was auto-applied> | <file>
```

**NEED-SIGNOFF** — higher stakes; could change agent behaviour or degrade output if wrong. Do NOT
apply. Write to review file (Step 3). Examples:
- Creating or editing a skill
- Adding or rewording a rule in CLAUDE.md
- Deleting a memory file or a rule
- Anything that would change how the agent behaves on a future task
- A metrics trend that suggests a systemic fix (even if the fix itself seems obvious)

**MORE-CONTEXT** — cannot self-decide; need Andrew's input. Do NOT apply. Write to review file
(Step 3), flagged clearly as a question. Examples:
- Conflicting information across two memory files (can't determine which is canonical)
- A promotion-queue item with no clear target location
- A finding that could justify multiple different rule changes

---

### Step 3 — Write the review file (if any NEED-SIGNOFF or MORE-CONTEXT items)

Write to `~/.claude/improve/review/YYYY-MM-DD.md` (today's date). If a file for today already
exists, append to it — do not overwrite.

**File format:**

```markdown
# Improvement Review — YYYY-MM-DD

<!-- Andrew: read top-to-bottom, check boxes, save. The improve-system skill reads the checkboxes
     on the next run and applies approved items. -->

## NEED-SIGNOFF

### [Short title for the change]

**Proposed change:**
[Diff or precise prose description — specific enough that it can be applied without ambiguity]

**Rationale:**
[Why this matters, what evidence triggered it (source log / metrics entry / date)]

- [ ] approve   - [ ] reject   - [ ] approve + don't ask again

---

## MORE-CONTEXT

### [Short title for the question]

**Question:**
[What you need to decide, and what the two or more options are]

**Context:**
[Where the conflict or ambiguity came from]

- [ ] approve   - [ ] reject   - [ ] approve + don't ask again
```

Group all NEED-SIGNOFF items together and all MORE-CONTEXT items together so Andrew can review in
one pass. If only one type exists, omit the empty section header.

---

### Step 4 — Print summary

End with a plain-text summary (fits in one screen):

```
improve-system run — YYYY-MM-DD
  Auto-applied: N item(s)
  Awaiting sign-off: M item(s)  →  ~/.claude/improve/review/YYYY-MM-DD.md
  Sources scanned: [list of project dirs with logs]
  Next run: [Tue or Fri, whichever is next]
```

If N = 0 and M = 0, print:
```
improve-system run — YYYY-MM-DD
  Nothing to do. System is current.
```

---

## Schedule

Runs **Tuesday and Friday evenings** (typically 18:00–20:00 local), after the `sync-claude-sessions`
skill has processed that day's session logs. The actual cron/ScheduleWakeup trigger is wired
separately — this section documents the intended cadence for reference.

When run headlessly (`claude -p /improve-system`), all interactive clarification is suppressed.
Items that would require a question get bucketed into MORE-CONTEXT and written to the review file
instead of interrupting the run.

---

## File layout

```
~/.claude/skills/improve-system/
└── SKILL.md               # this file

~/.claude/improve/
├── changelog.md           # append-only log of auto-applied fixes
├── review/
│   └── YYYY-MM-DD.md      # sign-off queue (one file per run date)
└── sessions/
    ├── processed.json            # sync-claude-sessions scan watermark
    └── YYYY-MM-DD-candidates.md  # sync-claude-sessions findings digest (the actual input)
```

---

## Relationship to other skills

| Skill | When | What it handles |
|-------|------|-----------------|
| `revisit` | End of live session | Per-session retrospective, mistake taxonomy, metrics update |
| `improve-system` | Tue + Fri cron | Ingestion-derived findings, cross-project systemic fixes, index drift |
| `sync-claude-sessions` | Before improve-system | Aggregates raw session logs into structured candidates |

Never invoke `revisit` from within `improve-system`. They share no outputs — `revisit` writes to
`conversations/metrics.md` inside a project; `improve-system` writes to `~/.claude/improve/`.
