001 v1.0 Core Learning Documented

Capturing Patterns

Observes your Claude Code sessions to detect recurring workflows, commands, and file access patterns.

Structured Data

Capability Metadata

Field	Value
ID	CAP-001
Version	v1.0
Domain	Core Learning
Status	Documented
Related	CAP-002, CAP-003, CAP-010
Source	`src/observation/session-observer.ts`
Output	.planning/patterns/sessions.jsonl
Toggle	observe_sessions (integration.json)

Configuration Reference

Toggle: observe_sessions in integration.json

{
  "observe_sessions": true
}

Output file: .planning/patterns/sessions.jsonl

Trigger: /sc:observe — manual session snapshot

Auto-trigger: post-commit hook (installed by CAP-037)

Technical Specifications

Class: SessionObserver

// Observation record written to sessions.jsonl
interface ObservationRecord {
  timestamp: string;       // ISO 8601 UTC
  session_id: string;      // UUID v4
  tool_sequence: string[]; // Ordered tool names
  files_accessed: string[]; // Relative paths
  commands_run: string[];  // Shell commands
  pattern_hash: string;    // SHA-256 of sequence
  checksum: string;        // JSONL integrity (CAP-032)
}

// Observer interface
class SessionObserver {
  observe(): ObservationRecord;
  flush(): void;
  getSessionId(): string;
}

JSONL format: one JSON object per line, append-only

Overview

Capturing Patterns is the foundational capability of the GSD Skill-Creator — it is the system's eyes and ears. Every time you use Claude Code, the SessionObserver silently watches what happens: which tools you reach for in sequence, which files you touch, which shell commands you run. This raw observational data is the raw material from which everything else in the learning loop is built.

The observation data is written as newline-delimited JSON (JSONL) to .planning/patterns/sessions.jsonl. Each record captures a snapshot of one session or commit boundary: a timestamp, a unique session ID, the ordered sequence of tools used, the files accessed, and a hash of the sequence for cross-session comparison. This append-only log is the input to Pattern Discovery (CAP-010), which scans the log to find recurring workflows.

Without Capturing Patterns, there is nothing to learn from. Every skill the system eventually suggests, every agent it composes, every workflow it optimizes — all of it traces back to the observations made here, in the humble JSONL file in your project directory.

History

Capturing Patterns was one of the original six capabilities shipped in v1.0. The initial implementation was simple: a lightweight observer that hooked into Claude Code's session lifecycle and wrote tool usage events to a JSONL file. The design decision to use JSONL — newline-delimited JSON — was deliberate: it allows append-only writes (crash-safe), easy streaming reads, and compatibility with standard Unix tools like jq and tail.

In v1.10, the observation system gained integrity checking (SHA-256 checksums, rate limiting, and anomaly detection — see CAP-032). In v1.11, a POSIX shell post-commit hook was introduced so that observations could be captured automatically at commit boundaries without any manual invocation. By v1.14, the observation records were linked into the full promotion pipeline, enabling cross-session stability analysis and determinism classification. The simple JSONL file of v1.0 had become the ground truth for a multi-stage machine learning pipeline.

Key Concepts

For Students & Teachers

Imagine you have a very attentive teacher's aide standing behind you as you work. Every time you do something — open a file, run a command, use a tool — the aide quietly writes it down in a notebook. They're not judging you or interrupting; they're just watching and recording.

That notebook is sessions.jsonl. It's a plain text file where each line records one snapshot of what happened during your session. Later, another part of the system (Pattern Discovery, CAP-010) reads through all those notebook pages and looks for things you do over and over again — like always running lint before tests, or always reading the same config file before editing it.

The key insight is that you don't have to decide what's worth remembering. The observer captures everything, and pattern detection figures out what's significant. You just work; the system watches and learns. This is what makes it different from manually writing a skill: the skill emerges from what you actually do, not what you think you do.

Usage Examples

Example 1: Trigger a manual session snapshot

# Inside a Claude Code session, run the observe command
/sc:observe

# The observer writes a record to sessions.jsonl immediately.
# Use this before ending a session to capture the current state.

Example 2: View recent observations

# View the 5 most recent observation records (pretty-printed)
tail -5 .planning/patterns/sessions.jsonl | jq '.'

# Example output:
{
  "timestamp": "2024-03-15T14:22:01Z",
  "session_id": "a1b2c3d4-...",
  "tool_sequence": ["Read", "Edit", "Bash", "Bash", "Read"],
  "files_accessed": ["src/observer.ts", "tests/observer.test.ts"],
  "commands_run": ["npm test", "git add -p"],
  "pattern_hash": "sha256:7e3a9f...",
  "checksum": "sha256:1d4c2b..."
}

Example 3: Count unique pattern hashes

# Count how many distinct tool sequences have been observed
jq -r '.pattern_hash' .planning/patterns/sessions.jsonl | sort -u | wc -l

# Count how many times the most common sequence appeared
jq -r '.pattern_hash' .planning/patterns/sessions.jsonl \
  | sort | uniq -c | sort -rn | head -5

Example 4: Enable/disable observation in integration.json

# integration.json (project root or ~/.claude/)
{
  "observe_sessions": true,   // set false to disable
  "observation_rate_limit": 100  // max records per hour (CAP-032)
}