pattern-capture

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

---
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):

<EXTREMELY-IMPORTANT>
**[RULE IN ALL CAPS]. This is not negotiable.**

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

Fact Row entry (for incident-learned knowledge the agent overrode or lacked — supersedes Rationalization Table entries, v5.36.0):

- <Non-derivable fact from the observed incident — number / threshold / tool quirk / mechanic>.
  <Consequence of ignoring it, as a property of the action: counterproductive / unhelpful / dishonest / incompetent.>

Litmus before adding: could a strong model derive this from the rule itself? If yes, strengthen the rule statement instead of adding a row.

Red Flag entry (for observable wrong actions — action-targeted, never "if you catch yourself thinking"):

- **About to <observable behavior>** → STOP. <concrete harm — one line>.

For VALIDATION HOOKS

Generate a PreToolUse or PostToolUse hook:

// 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

**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.

**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 confusion. Read the entire SKILL.md before modifying it.

Red Flags

• About to create a skill for a one-sentence rule → STOP. Over-engineering; a memory entry suffices — use the classification tree.
• About to add enforcement without observed violations → STOP. Speculative enforcement constrains legitimate work and devalues existing Iron Laws; wait for 2+ real instances.
• About to modify a skill without reading it in full → STOP. That creates conflicts with existing patterns; read the full SKILL.md first.
• About to create a validation hook for a subjective rule → STOP. Hooks need programmatic detection — "code quality" isn't checkable; use a Red Flag or memory instead.
• About to skip user confirmation for proactively detected patterns → STOP. The classification may be wrong or unwanted; always present findings before generating.

Pattern Capture Facts

• A captured pattern goes to the ONE most relevant skill — shotgun-adding it to every plausible skill creates maintenance burden and contradictions, the opposite of the de-duplication this skill exists for.

Integration Points

System	How Pattern-Capture Integrates
continuous-learning	Consumes user_corrections patterns as input; pattern-capture classifies and routes them
skill-creator	Delegates learned skill generation; provides evidence and enforcement level
workflow-creator	Informational — when adding enforcement to a workflow skill, consult workflow-creator's audit mode to verify the addition fits the workflow's phase structure
Memory system	Primary output target — most patterns become feedback memories
Hook system	Secondary output — programmatically detectable anti-patterns become hooks

Examples

Example 1: Simple Behavioral Rule → Memory

Evidence: User said "stop summarizing at the end" in 3 sessions Classification: WHEN to do something → tool selection? No → workflow? No → MEMORY (feedback) Artifact:

---
name: feedback_no_trailing_summaries
description: Do not add summary paragraphs after completing a task — user reads diffs directly
type: feedback
---
Do not summarize what you just did at the end of responses. The user reads diffs and tool output directly.

**Context:** Trailing summaries waste time and feel patronizing to experienced users.
**Source:** Corrected 3 times across sessions.

Example 2: Build Verification → Enforcement Pattern

Evidence: Agent claimed "build passes" without running build in 4 sessions Classification: HOW → multi-step verification? Yes → but dev-verify already handles this → ENFORCEMENT PATTERN Artifact: Add to dev-verify's Red Flags table:

| "Build should still pass from earlier" | Earlier results are stale — any code change invalidates them | Run `npm run build` fresh RIGHT NOW |

Example 3: No Mocks in Integration Tests → Validation Hook

Evidence: Agent used jest.mock() in integration test files 3 times Classification: WHAT NOT TO DO → programmatically detectable? Yes (grep for jest.mock in tests/integration/) → VALIDATION HOOK Artifact: PostToolUse hook on Write/Edit that warns when jest.mock appears in integration test files.

Example 4: Project-Specific Convention → Project Memory

Evidence: User corrected jq syntax 3 times — container uses jq 1.6, not 1.7 Classification: HOW → single rule → project-specific → MEMORY (project) Artifact:

---
name: project_jq_16_explicit_syntax
description: NanoClaw container runs jq 1.6 which requires explicit field syntax, not shorthand
type: project
---
Container runs jq 1.6. Always use explicit syntax: `{title: .title}` not `{title, location: expr}`.

**Applies to:** NanoClaw container agent, any jq commands in container scripts.
**Context:** jq 1.6 does not support mixing shorthand + explicit fields. Causes silent failures.
**Source:** Corrected 3 times across sessions.

Example 5: Complex Debugging Procedure → Learned Skill

Evidence: User walked through the same pixi debugging steps in 3 sessions Classification: HOW → single rule? No (5+ steps) → multi-step verification? No → reusable? Yes → SKILL Artifact: Delegate to skill-creator with the debugging steps as input.

References

• Classification quick reference: references/classification-guide.md — fast-path matrix and enforcement strength ladder
• Artifact templates: references/artifact-templates.md — copy-paste templates for all artifact types with formatting guidance
• Enforcement checklist: references/enforcement-checklist.md — full 12-pattern reference (when adding enforcement to existing skills)
• Continuous-learning: ../continuous-learning/SKILL.md — upstream pattern detection (feeds into this skill)
• Skill-creator: ../skill-creator/SKILL.md — downstream skill generation (this skill delegates to it for learned skills)