learn

SKILL.md preview

---
name: learn
description: After completing a task, capture learnings by updating AI tool configuration. Creates or updates rules, agents, and context files based on what was discovered — in the native format for each tool (Claude Code, VS Code Copilot, Cursor, AGENTS.md). Use after any task where something surprised you, went wrong, or produced a reusable insight.
---

# Learn — Update AI Tool Configuration From Experience

## Purpose

After completing a task, turn what you learned into native artifacts for all configured AI tools so the next task benefits automatically. The output is always a rule, agent update, or context file update — never a log file or template.

## When to Use

### Manual Trigger
- After any task where something surprised you or went wrong
- After discovering a pattern worth preserving
- After stepping on a landmine that wasn't documented
- After working in a module that had no CLAUDE.md context
- Skip for routine tasks where nothing new was learned

### Automatic Trigger (run without being asked)
Run `/learn` automatically when any of these signals occur during a session:

| Signal | What happened | What to capture |
|--------|--------------|-----------------|
| **User corrects your approach** | "No, don't do it that way — use X" | **Pattern** — the correct approach |
| **Same fix requested twice** | User asks to fix the same issue/area again | **Landmine** — the fragile area and root cause |
| **Your change breaks something** | Tests fail, build breaks, behavior regresses | **Landmine** — what broke and why |
| **User rejects generated code** | "That's wrong", "revert that", user undoes your change | **Pattern or Landmine** — what was wrong, what's correct |
| **Undocumented convention discovered** | Code follows a pattern not in any rule | **Pattern** — document it |
| **Undocumented trap hit** | Something looked safe but caused problems | **Landmine** — document the trap |

**Auto-trigger workflow:**
1. Detect the signal during normal work
2. Finish the immediate fix or correction first
3. Then run `/learn` — start from Step 1 below
4. The signal itself provides the learning — you don't need the user to describe it

## Content Depth

Generated rules must carry enough depth to be genuinely useful. Use two content structures from the project's knowledge base:

- **Pattern structure** (`skills/_references/patterns/_TEMPLATE.md`) — for conventions and reusable approaches. Follow the full template: When to Use, Problem It Solves, Core Approach with step-by-step code examples, Best Practices, Common Mistakes with wrong/fix code, Variations, Related patterns and landmines.
- **Landmine structure** (`skills/_references/landmines/_TEMPLATE.md`) — for danger zones and known traps. Follow the full template: Severity, Symptoms, Root Cause, The Trap, Safe Approach (Don't/Do with code), Validation, Prevention, Related patterns and landmines.

**Line limits:**
- **Context files** (CLAUDE.md, AGENTS.md, copilot-instructions.md): MUST stay under **100 lines** (max 125 if critical context would be lost). Split into multiple scoped files rather than exceeding.
- **Pattern and landmine rules**: Should be as detailed as the templates require — typically **50-150 lines**. Depth and working code examples matter more than brevity.

## Tool Target Preferences

Before generating any output, check for `.north-starr.json` in the project root:

```json
{
  "version": 1,
  "targets": ["claude", "copilot", "cursor"]
}
```

- If the file exists, only generate artifacts for the listed targets
- If the file is missing, generate for all tools (backward compatible)
- "All formats" throughout this skill means **enabled target formats only**
- `AGENTS.md` is always updated regardless of preferences (it's universal)

## Workflow

### Step 1: Identify What Was Learned

Ask these questions about the completed task:

1. **Surprises** — Did anything behave differently than expected?
2. **Friction** — Where did you slow down, get stuck, or 

…