learning-quality

Learning Quality Skill

This skill defines when and how to capture learnings during ClosedLoop runs.

Decision Tree: Should I Capture This?

Before writing a learning, run through this decision tree in order:

1. Did I make a mistake and correct it, or discover something non-obvious?
   NO  → Don't capture (no learnings event)
   YES → Continue

2. Is it a config value? (specific URL, file path, project command, type name)
   YES → Write to CLAUDE.md (project scope), not org-patterns
   NO  → Continue

3. Is it tied to a single feature/bug with no generalizable principle?
   YES → SKIP
   NO  → Continue

4. Will it still be true in 6 months?
   NO  → SKIP (or generalize the principle)
   YES → Continue

5. Does it already exist in org-patterns.toon or CLAUDE.md?
   YES → SKIP (or note "Supersedes: [old pattern]" if correcting)
   NO  → CAPTURE IT

Note: Even "basic" knowledge is worth capturing if you actually made that mistake. These learnings exist because LLM agents struggle with certain patterns that humans might consider obvious. The goal is to help future agent runs avoid the same mistakes.

Hard Rejection Criteria

SKIP if ANY of these apply:

Note: Even patterns that seem like "basic knowledge" are worth capturing if you actually made that mistake. These learnings exist because LLM agents struggle with certain patterns. The goal is to help future agent runs avoid the same mistakes.

Capture Workflow

When you have a learning worth capturing:

Step 1: Classify Scope

Step 2: Generalize if Needed

Extract the underlying principle, not the specific instance.

Test: Would this help someone working on a different feature?

Step 3: Write the Pattern

Formula: [When/Where] + [specific action] + [context]

Step 4: Check for Conflicts

Before writing:

1. Check $CLOSEDLOOP_WORKDIR/.learnings/pending/ for learnings in this run
2. Check project CLAUDE.md "Learned Patterns" section
3. Check ~/.closedloop-ai/learnings/org-patterns.toon

If contradiction exists (existing says "do X", new says "don't do X"):

• Verify which is correct based on evidence
• Capture only the correct one
• Add "Supersedes: [old pattern]" if correcting

Step 5: Write the File

Output location:

$CLOSEDLOOP_WORKDIR/.learnings/pending/{agent-name}-$CLOSEDLOOP_AGENT_ID.json

Format:

{
  "what_happened": "Brief description of what occurred",
  "why": "Root cause or reason this matters",
  "fix_applied": "What you did to resolve it (if applicable)",
  "pattern_to_remember": "The actionable takeaway (minimum 20 chars)",
  "applies_to": ["agent-name"],
  "context": {
    "file": "relative/path/to/file.ext",
    "line": 42,
    "function": "function_name"
  }
}

Use ["*"] for applies_to if the pattern applies to all agents.

No Learnings Event

If you completed work without learnings to capture:

{
  "no_learnings": true,
  "reason": "Task was straightforward with no new patterns discovered"
}

This is valid—not every task produces learnings.

Quick Reference

Worth Capturing (Durable + Non-Obvious)

• Non-obvious tool behaviors not in docs
• Project conventions not inferable from code
• Architectural decisions with non-obvious rationale
• Gotchas that cost time and aren't documented

Not Worth Capturing

Scope Decision

Mentions specific paths/packages/features? → Project (CLAUDE.md)
Applies to any project with same tech?     → Global (org-patterns.toon)

Domain-Specific Guidance

Your agent definition may reference a domain-specific learning prompt (e.g., prompts/plan-writer-learning.md). If so, read it before capturing learnings.