Structured Data
Capability Metadata
| Field | Value |
|---|---|
| ID | CAP-005 |
| Version | v1.0 |
| Domain | Core Learning |
| Status | Documented |
| Related | CAP-001, CAP-002, CAP-003 |
| Max change | 20% per refinement |
| Min corrections | 3 before proposal fires |
| Cooldown | 7 days between refinements |
Configuration Reference
Toggle: enable_learning in integration.json
{
"enable_learning": true,
"max_change_percent": 20,
"min_corrections": 3,
"cooldown_days": 7
}Constraints are non-negotiable defaults — they may be tightened but not relaxed below the security baseline
Technical Specifications
Bounded refinement system:
interface CorrectionEvent {
skill_name: string; // Skill that was active
session_id: string; // Session where correction occurred
correction_type: string; // 'rewrite' | 'addition' | 'removal'
timestamp: string; // ISO 8601 UTC
}
interface RefinementProposal {
skill_name: string;
current_content: string;
proposed_content: string;
change_percent: number; // Must be ≤ 20%
evidence: CorrectionEvent[];
created_at: string;
}
class LearningEngine {
recordCorrection(event: CorrectionEvent): void;
getPendingProposals(): RefinementProposal[];
applyRefinement(skill_name: string): void; // requires confirmation
dismiss(skill_name: string): void;
}Overview
Learning is what makes the system improve over time rather than remain static. When you correct a Claude output — rewriting something it got wrong, changing an approach it took, adding something it missed — the system records that correction against the active skill. When the same skill has accumulated 3 or more corrections, a refinement proposal is generated.
The proposal is bounded: it can change at most 20% of the skill's content in a single refinement. This limit prevents runaway skill drift — a skill that changes too much too fast becomes unpredictable. The 7-day cooldown between refinements of the same skill ensures that corrections have time to prove themselves before another change is proposed. You must explicitly approve each refinement before it is applied. No skill is modified without your confirmation.
Corrections are the primary learning signal. When you rewrite something Claude wrote using a skill, you are implicitly saying "the skill's guidance was insufficient or wrong." The Learning engine captures that signal, aggregates it across sessions, and — when the evidence is strong enough — proposes a targeted improvement. The humans-in-the-loop design means the system gets better without becoming autonomous in ways that are unpredictable.
History
Learning was part of the v1.0 core, but the v1.0 implementation was opportunistic rather than principled. Early versions tracked corrections but had no bounds on how much a skill could change, no cooldown period, and no minimum correction count. The system would propose refinements after a single correction, potentially after every session. This led to skill instability — skills that changed so frequently they became hard to predict.
The bounded learning constraints — 20% max change, 3-correction minimum, 7-day cooldown — emerged from v1.10 security hardening in the Learning Safety capability (CAP-033). This was not a minor update: it was a fundamental architectural change to make the learning loop safe for production use. The v1.0 learning was an experiment; v1.10+ made it auditable, stable, and trustworthy. All three constraints are now enforced at the system level and cannot be relaxed below their baseline values, even in configuration.
Key Concepts
Think of it like a teacher who notices you keep making the same grammatical error. They don't rewrite your essay without asking — they wait until they've seen the error consistently (3 times), then suggest a specific correction (at most 20% of the essay). And they wait a week before suggesting another change, so you have time to practice what you just learned.
That's the learning system. It watches for patterns of correction — times when you change or fix something Claude produced — and uses those corrections as evidence that a skill needs updating. When there's enough evidence, it proposes the minimum necessary change and asks for your approval.
The 20% cap is especially important. If a skill can change 100% in one refinement, it's essentially a new skill — and you've lost the ability to predict what it will do. By limiting each change to 20%, the system ensures that skills evolve gradually and remain recognizable across their history.
Usage Examples
Example 1: How corrections are detected
# The system detects corrections automatically when you:
# 1. Rewrite content Claude produced (using the Edit tool after Claude wrote it)
# 2. Ask Claude to redo something it just did differently
# 3. Explicitly correct Claude: "No, you should have done X instead"
# Each detected correction is logged against the active skill:
# [correction recorded] skill: beautiful-commits, type: rewrite
# Evidence count: 2/3 — 1 more correction before proposal firesExample 2: Reviewing pending refinement proposals
# Inside a Claude Code session
/sc:suggest
# Output includes refinement proposals alongside skill suggestions:
# [REFINEMENT] beautiful-commits
# Evidence: 3 corrections (sessions a1b2, f3d4, 9g8h)
# Change: 15% of content (within 20% limit)
# Cooldown: last refined 14 days ago (cooldown: 7 days — OK)
# Preview? Accept? [y/n/preview]Example 3: Configure learning parameters
// integration.json — tighten learning constraints
{
"enable_learning": true,
"max_change_percent": 10, // more conservative: 10% max change
"min_corrections": 5, // require more evidence: 5 corrections
"cooldown_days": 14 // longer cooldown: two weeks
}
// Note: values can only be tightened, not relaxed below system baseline