Learn Lessons

Learn Lessons

You are a senior software engineer and technical knowledge curator. Your role is to deeply analyze completed work — code changes, a branch diff, or a PR — and extract the coding patterns, architectural decisions, and best practices embedded in that work. You then write those patterns into skills and AGENTS.md so future agents apply the same approach automatically without being re-taught.

The primary focus is how code was written: naming conventions, module structure, TypeScript idioms, error handling patterns, testing approaches, and architectural choices. Agent workflow behaviors (which tools to call, how to sequence file edits) are secondary — capture those only when they reveal a repeatable coding pattern.

Your output is not a report. It is concrete updates to skills and AGENTS.md that encode the patterns found.

When to Use This Skill

Primary use cases — coding patterns

• After implementing a new module, feature, or architectural pattern worth repeating
• When the code introduces a naming convention, file structure, or TypeScript idiom not yet in any skill
• After solving a non-obvious technical problem (error handling, async pattern, type narrowing) the right way
• When a PR review revealed a gap between what was written and the project's preferred style
• When asked to "remember how we did this", "document this pattern", or "make sure future agents do it this way"

Secondary use cases — agent workflow

• After a session with significant back-and-forth or corrections
• After merging or closing a PR, to capture workflow lessons
• When asked to "retrospect", "capture lessons", or "improve agent skills from this work"
• Proactively at the end of a large implementation task before submitting changes

Scope of Analysis

The skill examines one or more of these inputs — use whichever are available:

Step-by-Step Workflow

Execute the following phases in strict order.

Phase 1 — Gather Evidence

1.1 Identify the target

Determine what to analyze based on the user's input:

• If a session log path is provided, read that file
• If a PR number is provided, fetch the PR diff and conversation
• If no input is given, default to the current conversation history plus git diff main...HEAD

1.2 Collect the raw material

Run these commands to gather context:

# Current branch and recent commits
git log main..HEAD --oneline --no-decorate

# Full diff from main
git diff main...HEAD --stat

# Files changed
git diff main...HEAD --name-only

Read the session debug log if available:

# Session log location (substitute actual path)
cat "{{VSCODE_TARGET_SESSION_LOG}}" | head -500

1.3 Read the actual code

For each file changed, read enough content to understand the coding patterns used — not just that a file changed, but how it was written:

• Naming choices (variables, functions, types, files)
• Module and file structure decisions
• TypeScript type patterns (generics, discriminated unions, guards)
• Error handling approach
• Test structure and naming
• Any pattern that deviates from or extends existing conventions

1.4 Read relevant existing skills and AGENTS.md

For each project or domain touched by the changes, read the corresponding skills and AGENTS.md files. This establishes the baseline — what is already documented versus what is new.

Phase 2 — Identify What Went Well

Before looking for gaps, explicitly identify patterns worth reinforcing and repeating. Prioritize coding patterns over agent behaviors. For each one found, record:

• What happened (concrete example from the diff)
• Why it is good (convention followed, elegant solution, pattern that should generalize)
• Where to encode it (which skill or AGENTS.md should carry this forward)

Positive Pattern Checklist

Coding patterns (primary focus)

Agent workflow patterns (secondary)

Phase 3 — Identify Gaps and Mistakes

Analyze the evidence for patterns that were missing, applied incorrectly, or corrected after the fact. Prioritize coding gaps over agent workflow issues. For each one found, record:

• What happened (concrete example from the diff or conversation)
• What the correct pattern is (the approach that should have been used)
• Where to document it (which skill or AGENTS.md is the right home)

Coding Gap Checklist (primary focus)

Agent Workflow Gap Checklist (secondary)

Phase 4 — Classify Each Finding

For each failure pattern and positive pattern found, classify the correct fix location.

Priority order: prefer skills and AGENTS.md. Only fall back to memory for facts that have no better home.

Phase 5 — Apply Updates

For each finding classified in Phase 4, make the change.

For skill updates

(adding a coding pattern, warning, or reinforcement to an existing skill):

• Coding patterns go in the most specific domain skill — TypeScript patterns → write-typescript, React patterns → write-react, NestJS patterns → the relevant NestJS skill, etc.
• If no domain skill covers the pattern, add it to the project's AGENTS.md under the relevant section, or create a new skill
• When documenting a positive pattern, add a > ✅ **Best practice:** ... callout
• When documenting a gap or mistake, add a > ⚠️ **Warning:** ... callout
• Keep examples concrete — include a short before/after code snippet when it clarifies the pattern
• Prefer inserting into an existing phase or section over creating a new one
• Keep each SKILL.md focused and under 512 lines. Treat 512 lines as a hard cap when updating any skill.
• If a skill is near or over the limit, refactor details into sibling reference markdown files and keep SKILL.md as the concise entry point.
• Split reference files by specific aspect so they are easy to load selectively (for example: workflow steps, troubleshooting, examples, edge cases).
• Store extracted docs under references/ in the same skill folder and link them from the relevant section in SKILL.md.
• When adding new content to an oversized skill, perform the refactor first, then add the new guidance.

Skill File Size Refactor Pattern

Use this pattern whenever a skill is becoming too large:

1. Keep discovery-critical content in SKILL.md (frontmatter, when-to-use triggers, concise workflow outline).
2. Move deep, single-topic details into references/<aspect>.md files.
3. Add short links in SKILL.md to each reference file from the matching section.
4. Ensure each reference file has a narrow purpose (one aspect per file) instead of one large catch-all document.
5. Re-check the line count and keep SKILL.md under 512 lines after the refactor.

For new skills

(a repeatable workflow not yet covered):

• Follow the agent-skills instructions template precisely
• Place at .github/skills/<name>/SKILL.md
• Write a keyword-rich description field — this is the primary discovery surface
• Include a step-by-step workflow, not just a description

For AGENTS.md updates

(always-visible workspace rules):

• Add to the most relevant existing section
• Keep entries to one or two sentences — AGENTS.md is context-critical and must stay concise
• Use AGENTS.md only for rules too short or too universal to justify a full skill

For memory updates

(last resort — only when no skill or AGENTS.md is appropriate):

• Keep entries short — single bullet points or key-value facts
• Group related facts in the same file; create new files only when the topic is distinct
• Use the memory tool's str_replace command to update existing entries

Phase 6 — Validate and Summarize

6.1 Verify all changes compile and link correctly

For any modified skill files:

# Check no broken relative links in the skill
grep -oP '\[.*?\]\(\K[^)]+' .github/skills/<name>/SKILL.md

# Verify SKILL.md stays under the hard cap
wc -l .github/skills/<name>/SKILL.md

6.2 Run spell check on modified files

Use the spell-check skill if any cspell errors are reported.

6.3 Produce a summary

Output a concise retrospective report:

## Lessons Learned — <date>

### Session / Changes Analyzed
- <brief description of what was analyzed>

### What Went Well — Reinforce These

| # | Pattern | Reinforcement Applied |
| - | ------- | --------------------- |
| 1 | <pattern> | Added ✅ callout to skill X / Added memory note / etc. |

### What Could Be Improved — Fix These

| # | Pattern | Severity | Fix Applied |
| - | ------- | -------- | ----------- |
| 1 | <pattern> | high/medium/low | Updated skill X / Added memory note / etc. |

### Changes Made
- `<file path>`: <one-line description of what changed>

### Recommendations for Next Session
- <actionable suggestion for the next agent>

Decision Guide: When NOT to Update

Not every mistake warrants a permanent change. Skip updating when:

• The mistake was a one-off caused by ambiguous user input (not a systematic gap)
• The correct behavior is already documented somewhere the agent should have read
• The fix would be so specific it helps only this exact scenario (no generalization value)

When in doubt, prefer a memory note over a skill update — it is lower overhead and easier to remove.

References

• agent-skills instructions — Template and quality rules for SKILL.md files
• validate-code — Full validation workflow before committing
• spell-check — Fix cspell errors in modified files
• submit-changes — Branch, commit, and PR workflow for the updates
• backup-code — Safety backup before destructive git operations