# Session Learning

> Produce a structured learning record after any /implement or /review session. Captures which skills were loaded, what worked, what routing was ambiguous, and what failure patterns were observed. Output feeds both per-skill references/failure-patterns.md and the global routing FAILURES rollup under the repository skill root. Run automatically at the end of every /implement and /review task — no user prompt required.

- Skill: `jakubmikolajek/session-learning` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add jakubmikolajek/session-learning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jakubmikolajek/session-learning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: JakubMikolajek (https://skillmd.com/u/jakubmikolajek)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/jakubmikolajek/session-learning

---


# Session Learning

This skill closes the feedback loop on the skill system itself. After every implementation or review session, it records what the agent observed about skill quality, routing accuracy, and failure patterns — so the system improves from real usage rather than speculation.

## When to Use

- Automatically at the end of every `/implement` or `/review` task
- After `/debug` when a root cause reveals a missing or incorrect skill section
- After `/multi-repo` when cross-repo routing decisions were made
- When the agent notices mid-session that a loaded skill was wrong, incomplete, or ambiguous

## When NOT to Use

- Session consisted only of answering a question with no file modifications
- Task was a single-response clarification with no skill loading involved
- User explicitly says "skip learning" or "no learning record needed"

## Core Principles

### Observation Over Inference

Only record patterns directly observed this session. Do not infer failure patterns from code not read, or routing quality from paths not taken.

### Repository-Aware Paths

Do not hardcode skill paths. Resolve a workspace skill root first:

- Use `.codex/skills` when the repository is bootstrapped under `.codex`
- Use `skills` when skills live at repository root

Use `[SKILLS_ROOT]` in all instructions and outputs below.

Path guardrail:
- Never emit mixed paths in one entry (for example both `skills/...` and `.codex/skills/...`)
- Resolve `[SKILLS_ROOT]` once per session-learning run, then reuse it everywhere (skill list, per-skill detail path, global rollup detail path)

### Run Evidence (if available)

Some orchestrators (a hybrid Claude + Codex session, for example) persist a
machine-readable run log for each delegation instead of relying purely on
in-context memory. When such evidence exists, ground Step 1-2 in it rather
than reconstructing everything from recollection:

- Look for `.ai/runs/YYYY-MM.jsonl` (or the project's documented equivalent)
  in the current project root before starting Step 1.
- If present, treat its `start`/`completion` events (route, preloads,
  model/effort actually used, `stop_reason`) as ground truth for what ran —
  do not silently override them with a differently-remembered version.
- Full event schema and the known gaps in what it captures (no timing, no
  original prompt in the completion half) are documented in
  `references/run-log-schema.md` in this skill.
- If no run log exists for this session (a standalone Codex-only run, or an
  orchestrator that doesn't produce one), proceed exactly as before — this
  is a best-effort grounding source, not a hard requirement to run this
  skill at all.
- Run evidence and the append-only `references/failure-patterns.md` /
  `routing/FAILURES.md` history are different things: evidence tells you
  *what ran*; the failure-pattern files are *your judgment* about what that
  run revealed. Consuming the former does not change how the latter is
  written.

### Two Destinations, One Pass

Every session-learning run produces output in two places:
1. **Per-skill**: `[SKILLS_ROOT]/<skill-name>/references/failure-patterns.md` — appended, never overwritten
2. **Global rollup**: `[SKILLS_ROOT]/routing/FAILURES.md` — appended with session date and skill reference

Both are updated in the same pass. Never defer one to a later session.

### Severity Levels

Each recorded failure or signal carries a severity:

| Level | Meaning |
|---|---|
| `CRITICAL` | Skill loaded but produced wrong output — caused a real implementation mistake |
| `WARN` | Skill loaded, output was partially wrong or incomplete — required manual correction |
| `ROUTING` | Wrong branch or skill was loaded first — agent had to backtrack |
| `MISSING` | Task required knowledge not present in any skill — agent had to improvise |
| `OK` | Skill loaded and used correctly — positive signal worth recording |

Record `OK` entries too — they confirm what is working and prevent unnecessary refactoring of healthy skills.

### Routing Quality vs Skill Quality

These are separate dimensions:
- **Routing quality**: Did the agent reach the right skill via the routing tree, or did it take wrong turns?
- **Skill quality**: Once the right skill was loaded, was its content accurate, complete, and actionable?

Always distinguish between them in the learning record. A routing problem is fixed in `AGENTS.md` or a routing branch file. A skill quality problem is fixed in the skill's `SKILL.md`.

### Tooling/Environment Signals

Treat operational failures as a separate signal type from routing and skill quality.

- Examples: `EMFILE`, file descriptor limits, CI runner limits, package registry outage, local permission errors
- These signals are not automatically a skill failure; classify them separately and attach evidence
- Record them under `session-learning` unless another skill explicitly owns the operational context

Severity guidance for tooling/environment signals:
- Use `WARN` when validation can continue with workaround or retry
- Use `CRITICAL` when required validation or delivery is blocked
- Use `MISSING` only when the skill system lacks guidance for a recurring operational pattern

Operational classification examples:

| Signal | Classification | Why |
|---|---|---|
| `EMFILE: too many open files` during build/test, rerun works | `WARN` | Execution degraded but delivery can continue |
| `EMFILE` reproducible and blocks mandatory test/build gate | `CRITICAL` | Required validation is blocked |
| Repeated `EMFILE`/runner-limit incidents with no guidance in skills | `MISSING` (+ paired `WARN`/`CRITICAL`) | Skill system needs durable troubleshooting instructions |

Required evidence fields for tooling/environment entries:
- **Command**: exact command that failed
- **Key output**: minimal error line proving the signal
- **Scope**: local machine, CI runner, container, or shared environment

---

## Session Learning Process

```
Session Learning progress:
- [ ] Step 1: List all skills loaded this session
- [ ] Step 2: Assess routing quality per skill
- [ ] Step 3: Assess skill content quality per skill
- [ ] Step 4: Identify failure patterns
- [ ] Step 5: Identify missing skills or sections
- [ ] Step 6: Identify tooling/environment signals
- [ ] Step 7: Append to per-skill failure-patterns.md
- [ ] Step 8: Append to global FAILURES.md
```

**Step 1: List all skills loaded this session**

Enumerate every skill file that was read during the session. Include routing branch files (e.g. `FRONTEND.md`, `WORKFLOW.md`). Format:

```
Skills loaded this session:
- [SKILLS_ROOT]/routing/WORKFLOW.md (routing branch)
- [SKILLS_ROOT]/debug-trace/SKILL.md (leaf skill)
- [SKILLS_ROOT]/nestjs/SKILL.md (leaf skill)
```

**Step 2: Assess routing quality per skill**

For each skill loaded, assess whether the routing path to reach it was correct and efficient:

- Did the right branch file point to this skill?
- Were any wrong branches visited before the correct one?
- Was the routing decision table ambiguous for this task type?
- Did the agent load this skill directly instead of via the tree (override)?

**Step 3: Assess skill content quality per skill**

For each leaf skill loaded, assess the content:

- Were the instructions complete enough to execute the task without improvising?
- Were any sections missing that this task required?
- Were any sections present that gave wrong or outdated guidance?
- Was the "When to Use" trigger accurate for this task?
- Were the anti-patterns table entries relevant to what was actually encountered?

**Step 4: Identify failure patterns**

A failure pattern is any situation where the skill system (routing + content) produced a worse outcome than it should have. This includes:

- Agent loaded wrong skill first and had to backtrack
- Agent had to improvise because skill content was incomplete
- Agent followed skill instructions that produced incorrect output
- Agent skipped a combination rule and the task suffered for it
- Two skills gave conflicting guidance on the same decision

**Step 5: Identify missing skills or sections**

Record any task requirements that no skill covered:

- Was there a technical pattern used that belongs in an existing skill but is absent?
- Was there a workflow scenario not handled by any routing branch?
- Was there a combination of skills that should be a documented recipe but isn't?

Recurring desktop-shell regression rule:
- If the same UI/native shell issue repeats (for example custom titlebar drag, maximize on double-click, startup window bounds), record a `MISSING` entry and explicitly propose a dedicated skill section or new skill + routing update.

**Step 6: Identify tooling/environment signals**

Record operational signals that affect execution quality but are not direct routing/content issues.

- Capture at least command, key output, and scope
- Confirm whether issue is local/transient or reproducible in shared environments
- If issue exposed a skill gap, add a paired `MISSING` entry with specific wording for the skill fix

**Step 7: Append to per-skill failure-patterns.md**

For each skill that has a non-OK entry, append to `[SKILLS_ROOT]/<skill-name>/references/failure-patterns.md`.

Create the file if it does not exist. Always append — never overwrite.

Format:

```markdown
## [YYYY-MM-DD] — [severity]: [short title]

**Task context**: [one-line description of the task where this was observed]
**Observed**: [what the skill did or failed to do]
**Impact**: [what went wrong as a result, or "none" if caught early]
**Suggested fix**: [specific section, wording, or rule to add/change/remove]
**Status**: [open | fixed in vX.Y.Z]
```

For tooling/environment entries, add evidence lines:

```markdown
**Command**: [exact command]
**Key output**: [single representative error line]
**Scope**: [local | CI | container | shared]
```

**Step 8: Append to global FAILURES.md**

Append a compact entry to `[SKILLS_ROOT]/routing/FAILURES.md`.

Create the file if it does not exist. Always append — never overwrite.

Format:

```markdown
## [YYYY-MM-DD] — [severity] — [skill-name]

[One-line summary of the failure or signal]
Detail: [SKILLS_ROOT]/[skill-name]/references/failure-patterns.md
```

---

## Output Templates

### Per-Skill failure-patterns.md (create if missing)

```markdown
# Failure Patterns — [skill-name]

This file is maintained by the `session-learning` skill.
Entries are appended automatically after /implement and /review sessions.
Human review is required before acting on any CRITICAL or WARN entry.

<!-- entries below, newest last -->
```

### Global FAILURES.md (create if missing)

```markdown
# Global Failure Pattern Rollup

Maintained by `session-learning`. Entries link to per-skill detail files.
Human review cadence: before each minor version bump.

| Date | Severity | Skill | Summary |
|---|---|---|---|
<!-- entries appended below -->
```

---

## Combination Rules

- Run AFTER `session-handoff` when both are triggered in the same session — handoff captures what was built, learning captures how the skill system performed
- Run BEFORE `skill-creator` when a `MISSING` entry suggests a new skill is needed — the learning record is the input to the skill scaffold
- `CRITICAL` entries should trigger a `/new-skill` or direct skill edit before the next session on the same codebase
- `ROUTING` entries require a change to `AGENTS.md` or a routing branch file — not the leaf skill

## Anti-Patterns to Avoid

| Anti-Pattern | Instead Do |
|---|---|
| Overwriting failure-patterns.md | Always append — history must not be lost |
| Recording only failures | Record OK entries too — confirms healthy skills |
| Deferring FAILURES.md update to later | Update both files in the same session-learning pass |
| Blaming skill quality for a routing problem | Distinguish routing vs content issues explicitly |
| Promoting a fix to a skill without human review | Mark as `open` — human reviews before applying |
| Writing vague failure descriptions | Be specific: which section, which instruction, what it caused |
| Inferring failures from tasks not performed | Only record what was directly observed this session |

## Connected Skills

- `session-handoff` — run handoff first; session-learning is the second step of session close
- `skill-creator` — use to act on MISSING entries that deserve a new skill
- `project-context` — if session-learning reveals a context gap, update project-context conventions
- `changelog-generator` — include skill system changes in release CHANGELOG entries