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:

Criterion	Example	Why
Specific URL/path/config	"Use https://github.com/org/repo"	Config, not principle → CLAUDE.md
Project-specific names	"Use MyProjectType not OtherType"	Belongs in CLAUDE.md
One-off bug fix	"Field X was null in row 123"	Not reusable
Already captured	(check pending/, CLAUDE.md, org-patterns.toon)	Avoid duplicates

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

Scope	Destination	Heuristic
Project	CLAUDE.md	Mentions specific file paths, package names, or project-unique features
Global	org-patterns.toon	Applies to any project using the same language/framework/tool

Step 2: Generalize if Needed

Extract the underlying principle, not the specific instance.

GitHubActionStatus uses SUCCESS not COMPLETED When using Prisma enums, verify valid values in schema.prisma - don't assume names adm-zip is already installed for webhooks Check existing dependencies before adding new packages for common functionality The workstream query checks parentId before title Implementation detail with no generalizable principle ARTIFACT_SECTIONS has ISSUE in two places Specific bug, not a pattern

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

Step 3: Write the Pattern

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

PRD 'secure authentication' in this org means Auth0 + JWT + httpOnly refresh cookies Always check for None before accessing .items() on optional dicts in FastAPI handlers E2E tests require API mocks via msw in tests/mocks/, never hit real endpoints Task 'add endpoint' is only VERIFIED if both route AND handler exist, not just route file Check for None Missing: where? when? why? Be careful with imports TypeScript catch blocks have type unknown in strict mode Documented in TS handbook - skip Run `pnpm test` for validation Project config → write to CLAUDE.md instead Templates should have type matching templateForType, not type: TEMPLATE Feature-specific decision that may change - skip or generalize

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

Category	Examples
Common knowledge	TS strict mode, git basics, debugging 101
Config values	URLs, file paths, project commands
Implementation details	Query order, field names, styling choices
Temporary	Bug workarounds, feature-specific decisions

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.