intent-layer-compound

Compound Learning Skill

TL;DR: Capture and triage learnings at the end of a work session. Runs conversation analysis, surfaces candidates, and integrates with proper scope routing.

---

When to Use

Run /intent-layer-compound after:

• Completing a feature or bug fix
• Finishing any significant work session
• Discovering non-obvious behaviors or gotchas
• When you want to capture learnings before ending the session

---

Three-Layer Workflow

Layer 1: AI Conversation Scan

Before prompting for manual capture, analyze the conversation for learning signals.

Scan for these patterns:

Pattern	Example Phrases	Learning Type
User corrections	"actually...", "no, you should...", "that's wrong"	pitfall
Discoveries	"interesting...", "I didn't know...", "turns out..."	insight
Better approaches	"a better way is...", "instead, try..."	pattern
Unexpected behaviors	"but it returned...", "weird, it..."	pitfall
Missing checks	"should have verified...", "forgot to check..."	check

For each candidate found:

1. Extract the relevant conversation snippet
2. Identify the learning type
3. Determine affected directory (if identifiable from context)
4. Present to user for confirmation

Example output:

Found 3 potential learnings in this conversation:

1. [pitfall] User corrected assumption about API response format
   Context: "Actually, the API returns a list when there are multiple results..."
   Affected: src/api/

2. [insight] Discovery about caching behavior
   Context: "Turns out the cache invalidates on every deploy..."
   Affected: (workflow-level)

3. [check] Missing verification identified
   Context: "Should have verified the schema before migration..."
   Affected: src/db/

Layer 2: Structured Prompts

After AI-surfaced candidates are reviewed, prompt for additional learnings:

Prompt sequence:

1. "Were there any corrections you made to my assumptions?"
2. "Did we discover any unexpected behaviors?"
3. "Are there any better approaches we figured out?"
4. "Any checks that would have helped if done earlier?"

For each "yes" response:

• Use the scan prompt from prompts/scan.md to extract details
• Capture via the existing capture_mistake.sh with pre-filled fields
• Assign appropriate learning type

Layer 3: Direct Integration

After candidates are confirmed, integrate each one directly using learn.sh:

For each confirmed candidate:

${CLAUDE_PLUGIN_ROOT}/scripts/learn.sh \
  --project [PROJECT_PATH] \
  --path [AFFECTED_PATH] \
  --type [pitfall|check|pattern|insight] \
  --title "[TITLE]" \
  --detail "[DETAIL]"

learn.sh handles deduplication automatically — if the learning already exists (≥60% word overlap), it exits with code 2 and reports "duplicate skipped".

Report outcomes to the user:

• Exit 0: "✓ Integrated into [AGENTS.md path]"
• Exit 2: "⊘ Duplicate skipped (already documented)"
• Exit 1: "✗ Error: [message]"

Show summary of what was integrated and where when all candidates are processed.

---

Resources

Scripts Used

Script	Purpose
learn.sh	Direct-write learning to AGENTS.md (dedup-gated)
capture_mistake.sh	Create learning report for pending queue (swarm use)

Prompts

Prompt	Purpose
prompts/scan.md	Conversation analysis for learning signals

---

Quick Start

/intent-layer-compound

Or with explicit project path:

/intent-layer-compound /path/to/project

---

Example Session

$ /intent-layer-compound

=== Intent Layer Compound Learning ===

[Layer 1: Conversation Scan]
Analyzing conversation for potential learnings...

Found 2 potential learnings:

1. [pitfall] API response format varies
   "Actually, the API can return either a dict or a list..."
   Path: src/api/

   Is this worth documenting? [y/n/edit]: y

2. [insight] Deploy triggers cache invalidation
   "Turns out the cache clears on every deploy..."
   Path: (workflow-level)

   Is this worth documenting? [y/n/edit]: y

[Layer 2: Additional Prompts]
Any other corrections you made to my assumptions? [y/n]: n
Any unexpected behaviors discovered? [y/n]: n
Any better approaches figured out? [y/n]: n

[Layer 3: Direct Integration]
Integrating 2 confirmed learnings...

1. ✓ pitfall added to ## Pitfalls in src/api/AGENTS.md
2. ✓ insight added to ## Context in CLAUDE.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Integrated: 2
  Duplicates: 0
  Errors:     0

Compound learning complete!

---

Scope Routing

The compound skill routes learnings to the appropriate location:

Learning captured
       │
       └─── Is it workflow-level? (insight, cross-cutting)
                    │
          ┌────────┴────────┐
          │                 │
         Yes                No
          │                 │
          ▼                 ▼
    Root CLAUDE.md    Covering AGENTS.md
    (global scope)    (local scope)

Global Scope (Root CLAUDE.md)

Use for:

• Workflow insights (build process, deployment, testing)
• Cross-cutting patterns that apply everywhere
• Project-wide conventions and decisions
• Learnings that don't belong to any specific directory

Local Scope (Covering AGENTS.md)

Use for:

• Code-specific pitfalls
• API behavior quirks
• Module-specific patterns
• Checks for particular operations

---

Integration with Hooks

The compound skill works with the existing learning loop hooks:

• PostToolUseFailure: Auto-captures failures → pending/
• Stop hook: Prompts for learnings if configured
• /intent-layer-compound: End-of-session synthesis

Run /intent-layer-compound to process any auto-captured learnings alongside manual capture.