# Arc Learning

> Use when you have accumulated instincts and want to cluster related ones into higher-level skills, commands, or agents. Use when instinct evolve suggests candidates. Use when you want to consolidate behavioral patterns into reusable abstractions.

- Skill: `tomevault-io/arc-learning` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/arc-learning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/arc-learning/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/arc-learning

---


# Instinct Clustering

## Overview

Cluster related instincts into higher-level abstractions: skills, commands, or agents. This skill analyzes accumulated behavioral patterns (instincts) and identifies groups that can be consolidated into reusable components.

**Position:** `observe → instincts → cluster (this skill) → skills/commands/agents`

## Quick Reference

| Task | Command |
|------|---------|
| **Scan instincts** | `node "${SKILL_ROOT}/scripts/learn.js" scan --project {p}` |
| **Preview clusters** | `node "${SKILL_ROOT}/scripts/learn.js" preview --project {p}` |
| **Generate artifact** | `node "${SKILL_ROOT}/scripts/learn.js" generate --cluster N --project {p} [--type skill\|command\|agent] [--name custom-name] [--dry-run]` |
| **List evolved** | `node "${SKILL_ROOT}/scripts/learn.js" list --project {p}` |

## Infrastructure Commands

**Set SKILL_ROOT** from skill loader header (`# SKILL_ROOT: ...`):
```bash
: "${SKILL_ROOT:=${ARCFORGE_ROOT:-}/skills/arc-learning}"
if [ ! -d "$SKILL_ROOT" ]; then
  echo "ERROR: SKILL_ROOT=$SKILL_ROOT does not exist. Set ARCFORGE_ROOT or SKILL_ROOT manually." >&2
  exit 1
fi
```

## Workflow

1. **Scan**: Load all instincts from `~/.claude/instincts/{project}/` and `global/`
2. **Cluster**: Group by domain, then within each domain use trigger fingerprint similarity (Jaccard >= 0.6) to find sub-clusters
3. **Filter**: Only process clusters with 3+ instincts, at least 1 with confidence >= 0.6
4. **Preview**: Display candidate clusters with type recommendations and suggested names
5. **Generate**: Create skill, command, or agent from a cluster (auto-classified or user-overridden)
6. **Track**: Record evolution to `~/.claude/evolved/evolved.jsonl` for deduplication

**Note:** Generated files are scaffolds — refine before deployment.

## When to Use

- `instinct evolve` suggests clustering candidates
- 5+ instincts accumulated in the same domain
- User wants to consolidate behavioral patterns into reusable components
- User explicitly asks to cluster or organize instincts

## When NOT to Use

- Fewer than 3 instincts in any domain
- User wants to save a single pattern (use /recall instead)
- User wants to reflect on diaries (use /reflect instead)
- User wants to confirm/contradict individual instincts (use arc-observing)

## Generation Types

Classification is hybrid: domain+threshold primary, keywords as tiebreaker.

| Rule | Condition | Type |
|------|-----------|------|
| 1 | Domain is `workflow` or `automation` + avg confidence >= 0.7 | **command** |
| 2 | Cluster size >= 3 + avg confidence >= 0.75 | **agent** |
| 3 | Default (no primary rule matches) | **skill** |

Tiebreaker: if behavioral tokens ("always", "prefer", "avoid") outnumber action tokens ("when starting", "when running") 2:1 → skill. Reverse → command.

Commands always produce a backing skill (arcforge convention). Source instincts are left in place after evolution.

## Key Principles

- **User-driven**: Preview clusters and let user decide what to create
- **Minimum cluster size**: 3+ instincts required per cluster
- **Quality threshold**: At least 1 instinct must have confidence >= 0.6
- **Source tracking**: Record which instincts were evolved via JSONL log
- **No re-evolution**: `isAlreadyEvolved()` prevents duplicate generation

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/gregoryho) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->