self-learning

Overview

The self-learning skill automatically discovers, understands, and persists project context across sessions. It builds a mental model of the codebase, tech stack, conventions, and team preferences by scanning actual project artifacts. Without self-learning, every session starts from zero — with it, the agent accumulates institutional knowledge that improves accuracy and reduces errors over time.

Announce at start: "I'm using the self-learning skill to understand this project."

Phase 1: Trigger Identification

Determine which trigger activated this skill:

STOP: Identify your trigger before proceeding. Different triggers require different phases.

Phase 2: Project Structure Scan

Use Explore agents to examine these files in order of priority:

Action: For each file found, extract key facts. Do NOT read every file — scan strategically.

STOP: Complete the structure scan before analyzing code patterns.

Phase 3: Code Pattern Analysis

Examine 3-5 representative files to identify patterns:

Action: Open 3-5 files from different areas of the codebase. Record observed patterns with specific examples.

Phase 4: Git History Analysis

git log --oneline -20          # Recent commits — development velocity, commit style
git shortlog -sn -20           # Active contributors
git branch -a                  # Branching strategy
git log --diff-filter=A --name-only --pretty=format: -10 | head -30  # Recently added files

Extract: Development velocity, commit message conventions, branching strategy, active areas.

STOP: Complete all discovery phases before persisting to memory.

Phase 5: Persist to Memory

Update the following memory files (create if they do not exist, append if they do):

memory/project-context.md

# Project Context
<!-- Updated by self-learning skill -->
<!-- Last updated: YYYY-MM-DD -->

## Purpose
[What this project does, who it is for]

## Tech Stack
- Language: [e.g., TypeScript 5.x]
- Framework: [e.g., Next.js 15]
- Database: [e.g., PostgreSQL via Prisma]
- Testing: [e.g., Vitest + Playwright]
- CI/CD: [e.g., GitHub Actions]

## Architecture
[e.g., Monorepo with apps/ and packages/]
[Key directories and their purposes]

## Key Dependencies
[Critical libraries and their roles]

memory/learned-patterns.md

# Learned Patterns
<!-- Updated by self-learning skill -->
<!-- Last updated: YYYY-MM-DD -->

## Naming Conventions
[What was observed with specific examples]

## Code Organization
[Import patterns, file structure, module boundaries]

## Error Handling
[How errors are handled in this project with examples]

## Testing Approach
[Framework, patterns, naming, coverage expectations]

memory/user-preferences.md

# User Preferences
<!-- Updated by self-learning skill -->
<!-- Last updated: YYYY-MM-DD -->

## Communication Style
[Terse? Detailed? Prefers code over explanation?]

## Workflow Preferences
[PR workflow? Branch naming? Commit style?]

## Review Preferences
[What they focus on in reviews?]

memory/decisions-log.md

# Decisions Log
<!-- Updated by self-learning and brainstorming skills -->

## YYYY-MM-DD: [Decision Title]
**Decision:** [What was decided]
**Context:** [Why this came up]
**Rationale:** [Why this was chosen over alternatives]
**Alternatives considered:** [What else was considered]

Phase 6: Correction Protocol

When the user corrects an assumption:

1. Acknowledge the correction immediately — do not defend the wrong assumption
2. Identify which memory file should be updated
3. Update the memory file with the correction, including date and context
4. Apply the correction to current work immediately
5. Propagate — check if the correction invalidates other assumptions in memory

Do NOT skip the memory update. Corrections that are not persisted will be repeated.

Phase 7: Session Start — Memory Validation

When memory files already exist:

1. Load all memory files from memory/ directory
2. Check Last updated dates — flag anything older than 30 days
3. Spot-check 2-3 facts against current codebase (e.g., does package.json still list the same framework?)
4. If discrepancies found, run a targeted re-scan of the changed area
5. Update stale entries with current information

Decision Table: Discovery Depth

Anti-Patterns / Common Mistakes

Anti-Rationalization Guards

Do NOT skip memory persistence. If you discovered it, write it down.

Integration Points

Concrete Examples

Discovery Command Sequence

# Step 1: Identify tech stack
cat package.json | head -50
# or
cat composer.json | head -50
# or
cat pyproject.toml

# Step 2: Check project structure
ls -la
ls -la src/ || ls -la app/ || ls -la lib/

# Step 3: Examine coding standards
cat tsconfig.json 2>/dev/null || cat phpstan.neon 2>/dev/null
cat .eslintrc* 2>/dev/null || cat .prettierrc* 2>/dev/null

# Step 4: Git activity
git log --oneline -20
git shortlog -sn -20

Memory Update After Correction

## 2026-03-15: Naming Convention Correction
**Previous assumption:** Project uses camelCase for database columns
**Correction:** Project uses snake_case for database columns (user corrected)
**Evidence:** Checked `migrations/` directory — all columns use snake_case
**Updated:** learned-patterns.md, Naming Conventions section

Key Principles

• Observe, do not assume — base learnings on evidence from the codebase
• Incremental updates — append to memory files, do not overwrite
• Verify before persisting — double-check observations with 2+ examples
• Respect corrections — user corrections override observations immediately
• Stay current — re-scan when significant changes occur

Skill Type

RIGID — Discovery phases must be followed in order. Memory persistence is mandatory. Corrections must be recorded immediately. Do not skip phases or rationalize away the need to scan.