learn - SKILL.md Agent Skill

name: learn description: Extract reusable patterns from recent work into instincts. Run after completing features, fixing bugs, or at session end to capture what the project learned.

/learn — Extract Patterns into Instincts

Analyze recent work (observations, git history, solutions) and extract reusable "instincts" — small learned behaviors with confidence scoring.

When to Use

After completing a feature or fixing a bug
At the end of a coding session
When you want to capture a pattern you noticed
Periodically to keep the project's knowledge current

Execution Flow

Step 1: Gather Evidence

Run these in parallel to collect data:

Git history — git log --oneline -20 for recent commits
Recent diffs — git diff HEAD~5..HEAD --stat for what changed
Observations — Read .atv/observations.jsonl for tool use patterns from hooks
Existing instincts — Read .atv/instincts/project.yaml (create if missing)
Solutions — Read docs/solutions/ for documented patterns

Step 2: Analyze Patterns

Look for recurring patterns across the evidence:

Code style patterns:

Error handling conventions (wrapping, custom types, sentinel errors)
Naming conventions (variable, function, file naming)
Import organization preferences
Comment style and documentation patterns

Workflow patterns:

Test-first vs test-after behavior
Commit granularity preferences
Branch naming conventions
Review practices

Architecture patterns:

Package/module organization
Dependency injection style
Interface usage patterns
Configuration management approach

Tool usage patterns (from observations.jsonl):

Frequently used shell commands
Common file editing sequences
Preferred build/test commands

Step 3: Create or Update Instincts

For each new pattern discovered, create an instinct entry. For patterns that match existing instincts, increase confidence and observation count.

Instinct format (YAML in .atv/instincts/project.yaml):

instincts:
  - id: kebab-case-unique-id
    trigger: "when [specific situation]"
    behavior: "do [specific action]"
    confidence: 0.5
    domain: code-style|testing|architecture|error-handling|workflow|tooling
    observations: 1
    first_seen: YYYY-MM-DD
    last_seen: YYYY-MM-DD
    evidence:
      - "commit abc123: wrapped all errors with fmt.Errorf"
      - "observed 3 times in observations.jsonl"

Confidence rules:

New instinct starts at 0.5
Each additional observation: +0.1 (capped at 0.95)
Contradictory evidence: -0.15
No observations for 30 days: -0.1
Minimum: 0.1 (below this, remove the instinct)

Important constraints:

Maximum 50 active instincts per project
Each instinct must be atomic — one trigger, one behavior
Triggers must be specific (not "when writing code")
Behaviors must be actionable (not "write good code")
Evidence must cite specific commits or observations

Step 4: Write Results

Write updated .atv/instincts/project.yaml
Ensure .atv/instincts/ directory exists

Step 5: Report

Show a summary:

Learning complete!

New instincts:
  + always-wrap-errors (0.5) — wrap errors with fmt.Errorf using %w
  + table-driven-tests (0.5) — use table-driven test pattern for Go tests

Updated instincts:
  ↑ prefer-early-returns (0.6 → 0.7) — 1 new observation
  ↑ run-tests-before-commit (0.7 → 0.8) — 2 new observations

Ready to evolve (confidence > 0.8):
  ★ run-tests-before-commit — consider /evolve to generate a skill

Total: X instincts (Y new, Z updated)
Instinct file: .atv/instincts/project.yaml

Notes

Instincts are project-scoped and committed to the repo — the whole team benefits
Run /instincts to see all learned patterns
Run /evolve when instincts reach high confidence to generate full skills
The observer hooks in .github/hooks/copilot-hooks.json automatically capture tool use data