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.