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:

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:

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:

## [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:

**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:

## [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)

# 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)

# 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

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