pattern-capture

What this skill does

# Pattern Capture

Detect repetitive feedback across sessions and convert it into the right enforcement artifact — a memory entry, a validation hook, an enforcement pattern, or a standalone skill.

## The Problem This Solves

Users give the same corrections repeatedly:
- "Don't mock the database in tests" (session 1, 3, 7, 12)
- "Use jq explicit syntax, not shorthand" (session 2, 5, 8)
- "Check the build before claiming it works" (session 1, 4, 6, 9, 11)

Each correction costs the user time and erodes trust. The DRY principle applies to prompting: **if you've said it twice, it should be automated.**

## When to Use

- User says "I keep telling you..." or "Again, don't..."
- You notice you're receiving the same type of correction
- At end of session, to audit what feedback was given
- Proactively, when continuous-learning detects `user_corrections` patterns
- User explicitly asks to capture a pattern or DRY their prompting

## Process

### Step 1: Gather Evidence

Collect instances of the repeated pattern. Sources (check in order):

```
1. Memory files (fastest)
   → Grep pattern="<keyword>" path="<memory_dir>" glob="*.md"
   → Look for feedback-type memories

2. Session transcripts (if CLAUDE_TRANSCRIPT_PATH is set)
   → Grep for user corrections: "no", "don't", "stop", "again", "I said"
   → Count occurrences of similar corrections

3. Spotless archives (if available, cross-session)
   → Search conversation history for repeated correction patterns

4. User report (always valid)
   → User says "I keep having to tell you X" = sufficient evidence
```

**Minimum evidence threshold:** 2 independent instances (same correction, different contexts). A single user report of "I keep telling you" counts as meeting threshold — trust the user's observation.

### Step 2: Classify the Pattern

Every repeated pattern maps to exactly ONE artifact type. Use this decision tree. **Evaluate branches top-to-bottom; stop at the FIRST match.**

```
Is the pattern about WHEN to do something?
  YES → Is it about tool/command selection?
    YES → MEMORY (feedback type)
    NO  → Is it about workflow sequencing?
      YES → ENFORCEMENT PATTERN (add to existing workflow skill)
      NO  → MEMORY (feedback type)
  NO  →
Is the pattern about HOW to do something?
  YES → Is it a single rule (< 3 sentences)?
    YES → Is it project-specific?
      YES → MEMORY (project type)
      NO  → MEMORY (feedback type)
    NO  → Does it require multi-step verification?
      YES → VALIDATION HOOK
      NO  → Is it reusable across projects?
        YES → SKILL (learned skill)
        NO  → MEMORY (feedback type)
  NO  →
Is the pattern about WHAT NOT to do?
  YES → Can the violation be detected programmatically?
    YES → VALIDATION HOOK
    NO  → RED FLAG (add to existing skill's Red Flags table)
  NO  →
Default → MEMORY (feedback type)
```

#### Artifact Type Reference

| Artifact | When | Example | Where It Lives |
|----------|------|---------|----------------|
| **Memory (feedback)** | Simple behavioral rule | "Don't add trailing summaries" | `<memory_dir>/feedback_*.md` |
| **Memory (project)** | Project-specific convention | "jq 1.6 in container, use explicit syntax" | `<memory_dir>/project_*.md` |
| **Enforcement pattern** | Workflow drift prevention | "Must run build before claiming completion" | Added to existing SKILL.md |
| **Validation hook** | Programmatically checkable | "No mocks in integration tests" | PreToolUse/PostToolUse hook |
| **Red Flag entry** | Anti-pattern with observable trigger | "About to use `git add .`" | Added to existing skill's table |
| **Learned skill** | Multi-step reusable procedure | "Debug pixi environment issues" | `~/.claude/skills/learned/` |

### Step 3: Generate the Artifact

Based on classification, generate the appropriate artifact:

#### For MEMORY entries

```markdown
---
name: feedback_<descriptive-slug>
description: <one-line description specific enough to match in future>
type: feedback
---

<The rule, stated clearly>

**Context:** <Why this matters — what went wrong when it was violated>
**Source:** <How this was discovered — "corrected N times" or "user reported">
```

Write to memory directory and update MEMORY.md index.

#### For ENFORCEMENT PATTERNS (added to existing skills)

Identify which skill the pattern belongs to, then add the appropriate enforcement element:

**Iron Law** (for high-drift actions the agent rationalizes skipping):
```markdown
<EXTREMELY-IMPORTANT>
**[RULE IN ALL CAPS]. This is not negotiable.**

[One sentence explaining concrete user harm if violated.]
</EXTREMELY-IMPORTANT>
```

**Rationalization Table entry** (for patterns where the agent makes excuses):
```markdown
| Excuse | Reality | Do Instead |
|--------|---------|------------|
| "<exact excuse the agent generates>" | "<why this is wrong>" | "<correct action>" |
```

**Red Flag entry** (for observable wrong actions):
```markdown
| Action | Why It's Wrong | Do Instead |
|--------|----------------|------------|
| "<observable behavior>" | "<concrete harm>" | "<correct alternative>" |
```

#### For VALIDATION HOOKS

Generate a PreToolUse or PostToolUse hook:

```typescript
// hooks/<hook-name>.ts
// Pattern: <description of what this catches>
// Source: User corrected this N times across sessions

export default {
  event: "PreToolUse",  // or PostToolUse
  name: "<tool-name>",  // e.g., "Bash", "Write", "Edit"
  async handler({ input }) {
    // Detection logic
    const violation = /* check for the anti-pattern */;
    if (violation) {
      return {
        decision: "block",  // or "ask"
        reason: "<explanation of why this is blocked>"
      };
    }
    return { decision: "approve" };
  }
};
```

#### For LEARNED SKILLS

Delegate to skill-creator:
```
Skill(skill="skill-creator", args="Create skill from captured pattern: <description>")
```

Provide the skill-creator with:
- Pattern description and evidence
- Example correct/incorrect behaviors
- Suggested enforcement level (from classification)

### Step 4: Verify Integration

After generating the artifact, verify it's properly integrated:

| Artifact Type | Verification |
|---------------|-------------|
| Memory | `Grep` for the memory file, verify MEMORY.md updated |
| Enforcement pattern | Read the modified SKILL.md, verify pattern appears in correct section |
| Validation hook | Syntax check the hook file, verify it's in the right hooks directory |
| Red Flag entry | Read the modified skill, verify table is well-formed |
| Learned skill | Verify SKILL.md exists with frontmatter, description is trigger-only |

### Step 5: Report

Output a summary:

```
## Pattern Captured

**Pattern:** <one-line description>
**Evidence:** <N instances across M sessions>
**Classification:** <artifact type>
**Artifact:** <file path or location>
**Prevention:** <how this prevents future repetition>
```

## Proactive Detection

When invoked without a specific pattern (e.g., "find repeated feedback"), scan all available sources:

1. Read all feedback-type memory files
2. Search session transcripts for correction language:
   - `"no,? (don't|stop|not|never|instead|again)"`
   - `"I (already|just) (told|said|asked|mentioned)"`
   - `"(wrong|incorrect|that's not|not what I)"`
3. Group similar corrections by semantic similarity
4. For each group with 2+ instances, run the classification tree
5. Present findings to user for confirmation before generating artifacts

## Iron Laws

<EXTREMELY-IMPORTANT>
**NEVER GENERATE AN ARTIFACT WITHOUT EVIDENCE. This is not negotiable.**

Fabricating patterns the user hasn't actually repeated leads to over-engineered enforcement that constrains legitimate behavior. Every artifact must trace to specific observed instances.
</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT>
**NEVER ADD ENFORCEMENT TO A SKILL WITHOUT READING THE FULL SKILL FIRST. This is not negotiable.**

Adding a Red Flag or Iron Law without understanding the skill's existing enforcement creates conflicts, duplicates, and c