| name | lesson-to-harness |
| description | Invoke when the user says "turn this session's repeated requests into rules/skills", "교훈 처리해줘", "규칙으로 박아줘", or when the agent detects EITHER a repeated user correction/preference in-session (same kind of correction 2x+, or an explicit "from now on do/don't ...") OR a recurring agent/technical failure class (the same kind of failure hit 2x+ in-session — e.g. fixing the same category of CI failure twice — even with no user correction). Mines lesson candidates from the session, proposes them for approval, and institutionalizes only the approved ones as neutral, universal principles wired into the repo harness (.agents/rules, AGENTS.md, related skills, harness scan / hooks) as a single source — never memory-only. Fixing an instance never closes a recurring mistake; only a mechanical prevention does. Operationalizes learning-loop.md. |
Lesson → Harness
The step-by-step "how" for learning-loop.md: mine repeated user
corrections and recurring agent/technical failure classes, and after approval institutionalize
them as rules enforced by the repo harness. The .claude/hooks/correction-detect.sh
UserPromptSubmit hook nudges this skill on strong preference/principle signals — on that nudge (or
self-detection), run the procedure. A one-off "just do X this once" is NOT a lesson.
Trigger cue (self-detection): when you find yourself fixing the same class of failure a second
time in a session — even with no user correction, e.g. the same category of CI/scan failure twice —
invoke this loop. Fixing the instance does not close a recurring mistake; only a mechanical
prevention (steps 8–9) does.
Procedure
- Mine the session — collect two kinds of candidate, each with evidence (where / how many
times): (a) items the user repeated or explicitly turned into a principle; and (b) recurring
agent/technical failure classes — the same kind of failure hit 2×+ in-session even with no
user correction (e.g. "fixed the same category of CI failure twice", the same scan tripped twice,
the same build/type error class recurred). Both kinds are lessons; the same mandatory steps 8–9
(mechanism + prove-it-fails) apply to each. Exclude one-off task-specific instructions.
- Propose + approve — present candidates; only user-approved ones proceed. Never
institutionalize without approval.
- Normalize — one neutral, universal principle per lesson (
Principle / Why / How to apply);
remove incident/blame/one-off phrasing.
- Choose the enforcement tier — A: hard gate → AGENTS.md Mandatory Rules row +
.agents/rules/<slug>.md + a harness:scan FAIL condition or .claude/hooks/ check;
B: process guidance → rule doc + skill checklist line + index entries; C: augment an
existing rule/skill.
- Generalize to the class, then sweep — a lesson is never about the one triggering instance.
Name the class (the invariant that reproduces the symptom anywhere it's violated), then
enumerate and fix every current instance in the repo in this change. The swept-instance
count is part of the report.
- Find every touchpoint —
.agents/rules/index.md, the AGENTS.md Mandatory Rules table,
related skills, and (when mechanically checkable) .claude/hooks/ + scripts/harness/*. No
partial wiring.
- Write — the canonical
.agents/rules/<slug>.md (neutral, domain-free) + references at all
touchpoints. One owner document per fact.
- Build the mechanism (mandatory — the lesson is not closed without it) — prose alone never
closes a lesson. Reach one of exactly two terminal states:
- Mechanized — a
harness:scan FAIL condition, hook check, or test that trips on the
violation (the default).
- Infeasible-now — a written, concrete obstacle plus a tracked backlog item to add the
check. "Hard to check" / "low value" / silence are not acceptable reasons.
- Prove the mechanism catches the incident — run the new check against the pre-fix state
(or a reproducing fixture) and confirm it FAILS, then against the fixed state and confirm it
PASSES. The check carries its own coverage and stays scoped to the class. Record the
before/after result.
- Ship per git-branch.md (branch → conventional commit → PR →
Pre-Merge Code-Review Gate → merge),
pnpm harness:scan green before the PR.
- Report — files wired, swept-instance count (step 5), mechanism terminal state (step 8),
prove result (step 9). No named terminal state = the lesson is not closed.
New recurring role → dispatch capability-extraction
When an approved lesson is "a new recurring role" (the session kept hand-building the same focused
subagent + thin orchestration skill), dispatch the thin
capability-extraction pipeline (capability-scout →
proposal-reviewer → agent-skill-author → the agent-def-convention guard) instead of
hand-rolling this loop — the guard is the step-8 mechanism terminal state for a role lesson.
Single source = the repo
The canonical home is the repo (.agents/, AGENTS.md) — never record a persistent lesson in
session/agent memory only. Memory may hold a copy; the repo copy is canonical.
See also
