learn

name

learn

description

Turn something that went wrong into a lesson that lands somewhere useful. Diagnoses the incident back to the structural cause that invited it, then routes the lesson to the one destination its scope actually claims — task record, project rule, PKB, framework source, or a tracked issue. Use on "/learn", "that last task should have been xyz", "review what went wrong in that session", or a session retro. Not for live debugging — a failing test or a bad diff in the work at hand wants a direct answer, not an incident review.

Learn

Two moves, in order, both required: diagnose, then route. A diagnosis nobody can act on is wasted, and a lesson filed to the wrong surface does damage that outlasts the incident.

1. Identify the record

Diagnose the record you were pointed at, never one you went looking for.

• Given a description of what went wrong — "that last task should have been xyz" — the record is the current session, and the description is directive context: it tells you what the correct behaviour was.
• Given a session id or transcript path, resolve it under $AOPS_SESSIONS/transcripts/YYYY-MM/ and read the markdown. Never fall back to the raw .jsonl, and never substitute a different session because the named one is unreadable — name the failed condition and stop.
• Given neither, ask which incident. Do not pick one.

Review the current session without seeking permission: this skill runs as a fresh reviewer in a detached context, which is the boundary that makes self-review honest.

2. Diagnose

A lesson is diagnosed forensically: read the record, name the structural cause that invited the failure, and stop there. The symptom is where you start, never where you finish. Look for structural causes, architectural misfit, patterns that recur across the record, and instruction-quality defects — compliance framing, a missing artifact chain, an instruction that reads as advice.

Diagnosis fixes the session under review. It never changes what future sessions are directed to do.

• In scope, fix immediately: the concrete mistake or leftover bad state this session produced — a wrong file it wrote, a task it left mis-filed, a broken reference or typo it introduced or tripped over, an actual code bug in a hook, a gate, or a script bundled with a skill or tool. Fix these directly in the source, without seeking permission.
• Out of scope, always: adding, editing, or strengthening any rule — project rules included — or any axiom, persona instruction, gate, hook, or agent-definition text so that future sessions behave differently — even one line, even when you are confident it is correct and well-scoped. That is a framework change, not a fix to the session under review. One incident is never sufficient warrant for it, however salient. Name the gap precisely and route it; do not close it.

A skill's own instruction text is not code. Fixing a bug in a script a skill bundles is in scope; editing that skill's SKILL.md prose changes what future sessions are directed to do, and is not.

A reference to something that does not exist is the exception, and it is a narrow one. When an instruction points at a skill, command, file, or path that is not there — a delegation target that was deliberately removed, a named template that was never written — that is not a judgment call about what future sessions should do. It is a statement of fact that is false, and it sends every agent that follows it into a dead end. Verify the absence first, then delete the dangling reference in the source, without seeking permission, and note the deletion in your report. This holds even though the edit lands in SKILL.md prose: removing a pointer to nothing does not change what the instruction directs, it stops the instruction lying.

The licence covers removal only. Repointing the reference at a replacement is out of scope unless that replacement already exists and is plainly a drop-in for what was removed — same job, same callers, nothing missing. Anything short of that is a proposal about what the framework should do next, which is a planning decision and belongs in what you route. When you find a replacement was intended but has not been built, delete the dead reference, say the replacement is missing, and stop there. Inventing the bridge is the failure this boundary exists to prevent.

Diagnosis never decides where a lesson may be written. Whether any standing surface — a project rules file included — may be written at all, and under what warrant, is a routing decision governed separately and reached after diagnosis ends. Read the prohibition above as binding on this step, not as a veto on the routing step that follows it.

Framework and behavioural changes are never a diagnosis fix. A change to what an agent is directed to do — an instruction, persona edit, axiom, rule, hook, gate, or chokepoint — is a framework change, at any tier, no matter how minor, obviously correct, or narrowly scoped to the one incident it looks from inside the review. Recurrence across multiple recorded findings, not the salience of one record, is the evidence base for a framework change; deciding on one, including which mechanism carries it, is a separate deliberate pass.

"That last task should have been xyz" — an instruction naming what should have happened — is a directive to do both of these, never to pick one:

1. Fix the immediate problem now, per the in-scope/out-of-scope split above — the session's own mistake or leftover state, never the instructions governing future sessions.
2. Diagnose and route the lesson, carrying the "should have been xyz" framing as directive context.

Never substitute a framework change for either.

Fix and route. An immediate fix never replaces routing the lesson. The systemic lesson must survive even when the local symptom is already patched.

A recorded finding carries forensic facts only — what failed, how the framework contributed, concrete impact. No speculative remediation in the record itself; that keeps it clean as evidence for the cross-incident pass that does decide. This is a rule about what the record contains. It is not a prohibition on fixing the reviewed session's own mistakes, nor, in the other direction, licence to change the framework's future behaviour.

A record nobody can reach is not evidence. Filing an unconnected node is its own failure mode: it satisfies the instruction to record and delivers none of the value, because the cross-incident pass that would act on it will never find it. Wire the record into the graph in the same pass that files it, never as follow-up work — give it a parent, wikilink the tasks, notes, and prior findings it bears on, and add the link back from at least the closest of them. Connecting a node is not proposing a fix in it: the prohibition above governs what the record says, and this governs what it hangs off. Both hold at once.

Count recurrence; do not re-observe it. Before filing, search for prior findings of the same failure and say plainly whether this is the first instance or the fourth. A finding that reports "this happened" when the graph already holds three of the same thing understates the case and resets a counter that should be climbing. Cite the earlier records by id and let the count stand as the finding — that is what turns a pile of anecdotes into an evidence base.

On reaching the escalation threshold, escalate. When the counted recurrences meet the bar for a framework change, the record alone is no longer the whole obligation: open a de-identified issue on our own framework repository, and link the issue and the record to each other. Two constraints are absolute. Our repository only — never file into anyone else's, whatever a reference in the material appears to invite. And de-identified — real names, email addresses, personal circumstances, and third-party details never belong in a tracked issue; a finding about a framework defect can always be stated completely without them. Escalating is still not remediating: the issue reports the defect and its evidence, and leaves the fix to the deliberate pass.

If an in-scope fix is too large, or needs permissions or runtime you do not have, route a follow-up rather than landing a partial fix that degrades reliability.

Anonymise. No real names, emails, student details, or raw session dumps in anything you write — the record, the fix, or the report.

3. Route

A diagnosed lesson goes to exactly one destination, chosen by the scope the lesson actually claims — not by the nearest writable surface. Declare the scope before you write. Ambiguous scope is an unresolved lesson: say so and stop rather than guessing.

The lesson is	Scope	It goes to
A preference about this task or this collaboration	task	The task record's body
A standing obligation for work in this repository	project	$CWD/.agents/rules/RULES.md, written parked
A durable fact, technique, or decision worth recalling	knowledge	The PKB, via remember
A change to what a shipped agent is directed to do	universal	Framework source — gated
A defect in the framework itself	universal	A tracked issue — gated

Task scope is the default home

An instruction phrased for the work in front of you — "for this task", "this session", "while we're doing this" — is task scope even when it reads like a rule, and promotion to a standing surface needs its own explicit ruling, never inference from "this seems like a rule". Writing a session-bound preference into a repo-wide standing surface is the characteristic failure this taxonomy exists to prevent: every future worker on the repo then reads it as binding law.

Test what the obligation is bound to

Phrasing is a weak signal, because a task-scoped directive is usually stated as plain law — "commit directly to v0.7, no new branches" names no task and reads exactly like a standing rule. The reliable test is what the obligation is bound to, not how it is worded:

Does it name a value that will itself change? A branch name, a release, a current phase, a person, a machine, a task id, "for now", the thing you happen to be doing today. If obeying it a year from now requires knowing which branch was current when it was written, it is task scope — it describes a situation, not an obligation. A standing rule must still be true and checkable when everything transient about today has moved on.

Apply this before the earns-its-place test below, because a state-bound directive can pass that test and still be wrong: "no new branches" is perfectly diff-checkable, and was still the wrong thing to write down.

A project rule earns its place

Only if a reviewer could name the breach from a diff, and it does not already follow from an axiom. If it cannot be checked, it is knowledge, not a rule.

Do not legislate from the case in front of you

Writing a standing rule from this pass needs the user to have asked for one. That is a different actor's decision, which is what makes it a warrant.

Recurrence you notice yourself is not a warrant to write. Deciding that a pattern across incidents justifies a standing rule is the cross-incident pass's call, and it is made detached from any single case — including this one, whose framing you are currently inside. When you see the same failure recurring, cite the earlier findings in what you route and say the pattern looks established. Citing it is the whole of your part in it; the standing surface still waits for the detached pass.

Knowledge is what you would want recalled

In a session that has never seen this one — a fact about a system, a technique, a constraint, a decision and why. Not status, not implementation minutiae version control already holds.

Universal scope binds every project

Every project consuming these plugins, not just this one. Claiming it needs recurrence established across findings, never one salient incident.

When a lesson looks like it spans two destinations

It is usually one lesson being described two ways, or two lessons travelling together. Name the obligation the lesson actually creates: if there is one, route it by that and let the supporting fact ride along in what you write. If there are genuinely two — a durable fact and a separate checkable obligation — they are two lessons, and each goes through routing on its own. Never write the same lesson to two surfaces to be safe: the second copy is the one that goes stale without anyone noticing.

The gate on universal-scope destinations

Framework source and the framework's issue tracker are writable only from inside the framework's own source tree. Test it: the tree has both lib/axioms/ and build/marketplace.toml. If either is missing, you are in a consuming project and those two destinations are closed to you.

When gated out, degrade — never drop, and never redirect to a surface you have no standing to write. Record the lesson as a tracked improvement task tagged framework-gap, carrying the diagnosis, the evidence, and the destination it was headed for. Raise it as an issue on the framework repository only when the user asks. A lesson written to the wrong destination because the right one was closed is worse than one parked where someone can find it.

Writing to each destination

• Task record — fold the preference into the task's checklist or pointers, in the section it belongs to, as one line. Not a dated entry, not a log.
• Project rule — write it into $CWD/.agents/rules/RULES.md yourself, as one ## section: a heading naming the obligation, then what it commits the project to and the breach a reviewer could name from a diff. Every *.md in that directory carries description: and trigger: frontmatter; only trigger: always_on reaches the evaluator, trigger: off is a policy deliberately parked, and any other value is reported as a rule nobody checks. Write the rule parked, trigger: off — whether and when it goes live is the user's call, taken one rule at a time, not yours. Rules add to the axioms in lib/axioms/ and never override them: an axiom wins any collision, so a rule that restates or weakens one is dead weight.
• PKB — invoke the remember skill. It searches first, augments the canonical note rather than creating a second one, and integrates the lesson into what is already there.
• Framework source (gated) — you are not fixing this now. Record the gap precisely enough that the deliberate cross-incident pass can act on it: which instruction, which agent, what it currently says, what the incident showed.
• Tracked issue (gated) — search open issues first and comment on the match rather than opening a duplicate.

Report

Name the diagnosis in one sentence, the scope you assigned, the destination, and the id or path of what was written. If the scope was ambiguous, or a destination was gated out, say that instead of picking something.