Lesson Resurface

Core Rule

Given a short task summary, return a ranked list of pointers to lessons under tasks/lessons/ (including _archive/) whose applies_to topic tags overlap with the task. Return paths only — never load, read, or paraphrase lesson bodies into context. The agent decides whether to Read each pointer.

Process

The deterministic loop (vocabulary discovery, scoring, supersession resolution, output formatting) lives in scripts/lesson-resurface.sh. The skill is a thin pass-through:

scripts/lesson-resurface.sh "<task summary>"

Or, if invoking without a CLI argument, set the env var:

LESSON_QUERY="<task summary>" scripts/lesson-resurface.sh

Read the helper's stdout. It already emits the exact output format described under ## Output Format below. Do not invent a different format — the helper is the source of truth.

Kit Context

Before running this skill, ensure session boot is done:

1. Read CODEBASE_MAP.md
2. Read CLAUDE.project.md if it exists
3. Read tasks/lessons/_index.md Top Rules section (already injected by session-start.sh)

This skill is the dormant-layer complement to Top Rules:

• Top Rules = active layer, auto-injected at session start
• Recently Added / By Topic = active discoverable layer in _index.md
• /lesson-resurface = surfaces lessons outside those layers — archived or superseded — when the current task touches a topic they covered

When to Use

Invoke with /lesson-resurface "<task summary>" when:

• Starting a new task on an area you suspect a prior session has touched
• A tasks/handoff-*.md resumption mentions a topic that may have an archived lesson (auth, migrations, deps, a specific module name)
• The active Top Rules feel insufficient and you want broader history before committing to an approach
• After Goal-Driven Reframing (in agent_docs/workflow.md), the restated goal mentions a topic vocabulary that overlaps with applies_to tags

Not for:

• Loading every lesson — boot already surfaces Top Rules; bulk loading defeats the purpose
• Reading lesson bodies in this skill — output is pointer-only
• Replacing /lesson-refresh — that skill handles lifecycle (keep/update/archive); this skill handles recall
• Cross-project search — operates within one repo's tasks/lessons/ tree

What the helper does (for reference)

1. Discovers the canonical applies_to vocabulary by scanning frontmatter across tasks/lessons/*.md + tasks/lessons/_archive/*.md.
2. Substring-matches the task summary (lowercased) against the vocabulary. If zero topics match, exits with "No matching topics" and stops.
3. Scores each lesson:
   • +3 per topic in applies_to that matches an extracted task topic
   • +1 per free-form tags entry that matches
   • −2 if status: archived
   • −1 if status: superseded
   • +1 if confidence: high
   • Drops lessons with score ≤ 0
4. Resolves supersession — if a matched lesson is status: superseded and an active lesson supersedes it AND that active lesson is already in the match list, drops the older one. The agent never reads deprecated rules unintentionally.
5. Emits the top-5 pointers in the format below.

Frontmatter parsing reads only the YAML block between the first pair of --- markers — body content is never loaded.

Output Format

The helper emits this exact shape (do not reformat downstream):

Matched lessons for topics [<comma-separated topics>]:

1. tasks/lessons/_archive/2025-12-01-deps-version-mismatch.md
   applies_to: [dependencies, plan-first]
   status: archived | confidence: high
   title: Conflicting peer-dep versions blocked the build

2. tasks/lessons/2026-03-04-auth-token-rotation.md
   applies_to: [auth, hooks]
   status: active | confidence: medium
   title: Rotating tokens without invalidating sessions

… 2 more matched (not shown).

These are pointers, not content. Read any that look relevant before proceeding; the bodies were intentionally NOT loaded.

If nothing matches above threshold:

No archived/superseded lessons match topics [<topics>]. Proceed with the Top Rules already in context.

If the query itself doesn't intersect the vocabulary:

No matching topics found in applies_to vocabulary; no lessons to resurface.

Rules

Always:

• Run scripts/lesson-resurface.sh for the deterministic loop — never re-implement scoring in the agent's reasoning
• Pass the helper's output through verbatim (the format is the contract)
• Show applies_to, status, confidence, and title from frontmatter — these are tiny and useful for the agent's decision to Read
• Never include ## Issue, ## Root Cause, ## Rule, or ## References text — those are the body; surfacing them is the agent's decision

Never:

• Print full lesson bodies (the helper deliberately doesn't load them)
• Load lesson bodies into the conversation context
• Summarize what a lesson says (the title is the summary; for more, the agent reads the file)
• Modify any file (this skill is read-only)

Smoke Test

Self-check before relying on results:

# 1. Confirm the helper returns the kit's example lesson on a known topic
./scripts/lesson-resurface.sh "scope-discipline"
# Expect: 1 result pointing at tasks/lessons/2026-04-15-example-tsconfig.md

# 2. Confirm a vocabulary miss is silent
./scripts/lesson-resurface.sh "unrelated nonsense words"
# Expect: "No matching topics found in applies_to vocabulary..."

# 3. Confirm env-var invocation works
LESSON_QUERY="tooling" ./scripts/lesson-resurface.sh
# Expect: same result as (1) — both topics in the lesson's applies_to

Regression coverage lives in bench/scenarios/s17-lesson-resurface-smoke.json.

Pairs With

• Goal-Driven Task Reframing (agent_docs/workflow.md) — extract canonical topics from the restated goal before running this skill
• /lesson-refresh — lifecycle (archive/promote/encode/supersede); this skill is the recall counterpart
• CLAUDE.md → Self-Improvement Loop — the active Top Rules layer; this skill surfaces the dormant complement
• scripts/lesson-graph.sh — generates the _index.md auto-sections; this skill consumes the same applies_to typed-relation graph

Out of Scope

• Vector / embedding search — topic-tag matching is intentionally simple and deterministic
• Auto-loading bodies on a confidence threshold — that's a different design (would defeat the "pointer-only" rule)
• Cross-repo search — kit operates within one project's tasks/lessons/
• Writing new lessons — that's the lesson template + user correction flow