010 v1.5 Pattern Intelligence Documented

Pattern Discovery

Scans session logs to discover recurring workflows and generate draft skills automatically.

Structured Data

Capability Metadata

Field	Value
ID	CAP-010
Version	v1.5
Domain	Pattern Intelligence
Status	Documented
Related	CAP-001, CAP-002, CAP-054, CAP-055
Source	`src/discovery/pattern-scanner.ts`
Algorithm	DBSCAN clustering

Configuration Reference

Toggle: enable_discovery in integration.json

{
  "enable_discovery": true,
  "min_cluster_size": 3,
  "similarity_threshold": 0.75,
  "draft_skill_output": ".claude/drafts/"
}

Min cluster size: minimum occurrences for a pattern to qualify

Trigger scan: skill-creator discover

Technical Specifications

Class: PatternScanner

// A discovered pattern cluster
interface DiscoveredPattern {
  id: string;               // Pattern identifier (hash)
  tool_sequence: string[];  // The repeating tool sequence
  occurrences: number;      // Times seen in sessions.jsonl
  sessions: string[];       // Session IDs containing pattern
  similarity_score: number; // Intra-cluster coherence (0–1)
  draft_skill_path: string; // Output path for draft YAML
}

// DBSCAN clustering parameters
interface ScanConfig {
  epsilon: number;          // Max distance between neighbors
  min_samples: number;      // Min points to form a cluster
  similarity_fn: "jaccard" | "edit_distance" | "cosine";
}

class PatternScanner {
  scan(logPath: string, config: ScanConfig): DiscoveredPattern[];
  generateDraftSkill(pattern: DiscoveredPattern): string;
  exportDraft(pattern: DiscoveredPattern, outputPath: string): void;
}

Algorithm: DBSCAN (Density-Based Spatial Clustering of Applications with Noise)

Overview

Pattern Discovery is the intelligence layer that elevates raw observation data into structured knowledge. Where Capturing Patterns (CAP-001) collects session records passively, Pattern Discovery actively scans the accumulated JSONL log to find clusters of similar tool sequences — sequences that appear repeatedly enough to suggest a reusable workflow. When a cluster is found, Pattern Discovery generates a draft skill stub for human review.

The clustering algorithm is DBSCAN (Density-Based Spatial Clustering of Applications with Noise) — a density-based algorithm that identifies clusters of arbitrary shape without requiring a preset cluster count. This is appropriate for tool sequences: you don't know in advance how many patterns exist in your session history. DBSCAN finds them by looking for regions of high density in sequence space, treating outlier sequences as noise rather than forcing them into a cluster.

When a cluster is found, Pattern Discovery outputs a draft skill YAML file to .claude/drafts/. The draft contains the discovered tool sequence, the number of occurrences, example session IDs, and a skeleton skill template with placeholder triggers and instructions. The user reviews the draft, fills in the narrative instructions, and promotes it to a live skill via the Suggesting Skills flow (CAP-002).

History

Pattern Discovery was introduced in v1.5, completing the foundational learning loop: observe (CAP-001) → discover (CAP-010) → suggest (CAP-002). The initial implementation used DBSCAN clustering for its density-based approach — well-suited to sequence data where clusters have irregular shapes and sizes and the total number of patterns is unknown in advance.

In v1.13, the Pipeline Learning capability (CAP-054) extended Pattern Discovery with an observation-to-list compiler and a Jaccard feedback engine. Where the original DBSCAN scanner treated all sequence occurrences equally, the Jaccard feedback engine weighted sequences by their stability across sessions — a sequence seen consistently across 30 sessions is a stronger pattern signal than one that appeared 30 times in the same afternoon.

Key Concepts

For Students & Teachers

Imagine reading through 200 pages of your own notes and circling every time you wrote about the same topic. Pattern Discovery does this for your Claude Code sessions — it reads thousands of recorded tool sequences and groups the similar ones together. If it finds you've done "read config → edit source → run tests" 15 times, it knows that's a pattern worth capturing.

DBSCAN is like a map that finds cities automatically, without being told how many cities to look for. Give it a map of dots (your tool sequences), and it finds the dense clusters (patterns) while ignoring the isolated dots (one-off sequences). You don't need to guess the number of clusters in advance — DBSCAN discovers whatever structure exists in the data.

Usage Examples

Example 1: Trigger a discovery scan

# Run pattern discovery against accumulated session log
skill-creator discover

# Output:
# Scanning .planning/patterns/sessions.jsonl (1,247 records)...
# Clustering with DBSCAN (epsilon=0.3, min_samples=3)...
# Found 4 pattern clusters:
#   Pattern-A: ["Read", "Edit", "Bash", "Bash"] — 23 occurrences
#   Pattern-B: ["Glob", "Read", "Edit", "Read"] — 18 occurrences
#   Pattern-C: ["Bash", "Read", "Write", "Bash"] — 11 occurrences
#   Pattern-D: ["Read", "Write", "Bash"] — 9 occurrences
# Draft skills written to .claude/drafts/

Example 2: Review discovered patterns

# .claude/drafts/pattern-a-draft.yaml
# Auto-generated by PatternScanner — review and edit before promoting

id: pattern-a-draft
tool_sequence: ["Read", "Edit", "Bash", "Bash"]
occurrences: 23
sessions:
  - "a1b2c3d4-..."
  - "e5f6g7h8-..."
  # ... (23 session IDs)

# === DRAFT SKILL STUB — FILL IN BELOW ===
triggers:
  - "FILL IN: what context triggers this workflow?"
instructions: |
  FILL IN: what should Claude do when this pattern is triggered?
name: "FILL IN: short skill name"

Example 3: Convert a pattern to a draft skill

# After reviewing the draft, promote to a live skill
skill-creator promote .claude/drafts/pattern-a-draft.yaml

# This passes the draft through the Suggesting Skills flow (CAP-002)
# You'll be prompted to confirm the skill name, triggers, and instructions
# On confirmation, the skill moves from .claude/drafts/ to .claude/commands/