instinct-review

name	instinct-review
description	Reviews/promotes/removes instincts from `.claude/instincts/*.md`. Triggers: instinct review, curate instincts, manage instincts, promote instinct.
effort	low
user-invocable	true
argument-hint	[--list | --promote <id> | --remove <id> | --clear]
allowed-tools	Bash, Read, Write, Glob

/instinct-review - Manage Learned Instincts

$ARGUMENTS

What This Does

Manages the instinct system that learns patterns from your sessions.

Instincts are stored in .claude/instincts/ and loaded at session start.

Commands

List all instincts

/instinct-review --list

Shows all instincts with confidence scores and source sessions.

Review and curate

/instinct-review

Interactive review: shows each instinct and asks promote/remove/keep.

Promote instinct (always apply)

/instinct-review --promote <filename>

Remove instinct

/instinct-review --remove <filename>

Clear all instincts

/instinct-review --clear

How Instincts Work

1. Extraction: At session end, the Stop hook extracts patterns from the session
2. Storage: Saved as .claude/instincts/<pattern-name>.md with confidence score
3. Loading: At session start, instincts are loaded and shown to Claude
4. Curation: Use /instinct-review to promote good ones and remove bad ones

Instinct Format

# Pattern: [pattern name]
Confidence: 0.85
Sessions: 3
Last seen: 2026-03-25

[Description of the pattern or preference]

Steps

1. Run ls .claude/instincts/ 2>/dev/null || echo "No instincts yet"
2. For each instinct file, read it and display confidence/summary
3. Based on $ARGUMENTS:
   • --list: display table of all instincts
   • --promote <id>: set confidence to 1.0, add "pinned" tag
   • --remove <id>: delete the file
   • --clear: delete all files in .claude/instincts/
   • no args: interactive review of each instinct
4. Report summary of changes made

Rules

• MUST list instincts with their source (session ID or date) so the user can judge provenance — anonymous instincts cannot be curated
• MUST confirm before --clear — this action is irreversible without a backup
• NEVER invent or edit instinct content — this skill curates existing files, it does not generate new ones
• NEVER promote an instinct with confidence < 0.7 without explicit user approval — low-confidence patterns are often one-off noise
• CRITICAL: the user owns the instinct list. Propose changes in interactive mode; apply silently only for explicit --promote, --remove, --clear flags.
• MANDATORY: after any destructive operation, print the deleted or modified filenames so the user has an audit trail

Gotchas

• Instincts live in project-local .claude/instincts/, not in ~/.softspark/ai-toolkit/. Running this skill in a different project sees a different set — do not treat the list as global state.
• The Stop hook that extracts instincts may write draft files even when no meaningful pattern was observed. A .claude/instincts/ with 40 files is usually 35 noise + 5 signal — curate ruthlessly.
• Promoted instincts (confidence = 1.0) load into every session's context, costing tokens. Too many pinned instincts bloat startup. Keep ≤10 pinned.
• Instinct files are plain markdown but the extraction format may evolve between ai-toolkit versions. A --clear after a version bump is often cleaner than trying to migrate old formats.
• The filename (<pattern-name>.md) is the identity used by --promote and --remove. Renaming files manually breaks those flags until the user reopens the review UI.

When NOT to Use

• To extract new instincts — extraction is automatic via the Stop hook
• To search past session memory — use /mem-search
• To edit global toolkit memory files — those live in ~/.claude/projects/*/memory/ and are managed by the auto-memory system, not this skill
• To permanently disable the instinct system — edit settings.json to remove the Stop hook; --clear only wipes current state, extraction continues on the next session