learn-define-patterns

name	learn-define-patterns
description	Analyze recent /define sessions to extract user preference patterns and write them to CLAUDE.md. Use when you want to learn from past define sessions, extract define patterns, improve future defines, or capture define preferences.
user-invocable	true

User request: $ARGUMENTS

Goal

Analyze recent /define session transcripts, extract patterns in how the user approaches /define interviews (probing preferences, trade-off defaults, recurring invariants, process guidance, quality gate adjustments), and write generalizable patterns to CLAUDE.md as ## /define Preferences. Future /define sessions see these preferences automatically because CLAUDE.md is loaded into context.

Why This Matters

Every /define session, users make the same corrections, add the same invariants, resolve the same trade-offs. Without learning, each session starts from zero. This skill closes the feedback loop: patterns from past sessions become probing hints for future ones.

Constraints

Constraint	Rule
User approval required	NEVER write to CLAUDE.md without presenting patterns to the user and getting explicit approval.
Merge, never overwrite	If a ## /define Preferences section already exists, merge new patterns with existing ones. Never blindly overwrite.
Semantic deduplication	When merging, identify patterns that say the same thing in different words and consolidate them. Don't just check for exact text matches.
Standard markdown only	Output uses ## headers, ### subheaders, - bullets, and <!-- date --> HTML comments. No custom syntax, no YAML, no special parsing.
Ask write target	Ask the user which CLAUDE.md to write to: project CLAUDE.md, user ~/.claude/CLAUDE.md, or both. Never assume.
Diff preview before write	Show the user exactly what will be added or changed in CLAUDE.md before writing.
Clean up temp files	Delete per-session analysis files from /tmp/ after aggregation is complete.

Session Discovery

Session JSONL files live at ~/.claude/projects/{project-path-encoded}/{session-id}.jsonl. Find recent sessions containing /define activity. If $ARGUMENTS specifies a session count, use that; otherwise use enough recent sessions for meaningful pattern signal.

No sessions found: Tell the user: "No /define sessions found in recent session history. Run a few /define sessions first, then try again."

Malformed files: Skip with a warning noting which files were skipped and why.

Per-Session Analysis

Use the define-session-analyzer agent to analyze each session independently. Each agent receives a session file path and an output path (/tmp/define-learn-{session-id}.md). Sessions with zero extractable patterns are normal — count them in the final summary.

Aggregated Output

The final output is a unified set of user preferences derived from all analyzed sessions.

Quality criteria for the aggregated output:

• Patterns organized by the 5+1 categories (Probing Hints, Trade-off Defaults, Recurring Invariants, Process Guidance, Quality Gate Adjustments, Other)
• Semantically equivalent patterns across sessions consolidated into one, with frequency noted
• Contradictions between sessions surfaced with evidence from each side — user resolves
• Each pattern classified as "project-specific" (references specific files/variables/entities) or "generalizable" (references categories/principles/domains) — user decides which to keep

What the user sees before approving:

• Pattern statement, session frequency, project-specific vs generalizable flag, any contradictions
• Batch selection (not per-pattern approval)
• Choice of write target: project CLAUDE.md, user ~/.claude/CLAUDE.md, or both
• Diff/preview of exact changes before writing

CLAUDE.md Output Format

## /define Preferences

### Probing Hints
- Pattern statement here <!-- 2026-03-01 -->

### Trade-off Defaults
- Pattern statement here <!-- 2026-03-01 -->

### Recurring Invariants
- Pattern statement here <!-- 2026-03-01 -->

### Process Guidance
- Pattern statement here <!-- 2026-03-01 -->

### Quality Gate Adjustments
- Pattern statement here <!-- 2026-03-01 -->

### Other
- Pattern statement here <!-- 2026-03-01 -->

When merging with an existing ## /define Preferences section: preserve all existing patterns and their date comments, deduplicate new patterns against existing ones by meaning (not just text match), add new patterns under the appropriate subcategory headers, and omit empty subcategories.

Precedence: When future /define sessions encounter a conflict between built-in task file guidance and patterns in ## /define Preferences, the user's patterns represent intentional preferences and take precedence.

Traceability: Each pattern includes an inline <!-- YYYY-MM-DD --> date comment. Users remove patterns by editing CLAUDE.md directly — no special tooling needed.

Summary

After writing, output a summary: sessions analyzed, sessions with patterns (and sessions with zero patterns), patterns extracted, patterns approved, contradictions found, and which CLAUDE.md was written to.