Roam Lesson Maintenance

---
name: roam-lesson-maintenance
description: Turn a reproduced or recurring Roam failure into a durable correction, regression control or narrowly scoped project skill, and reconcile conflicting lessons. Use when asked to preserve and apply lessons, not for routine note-taking, an unconfirmed allegation or every successful edit.
---

# Roam lesson maintenance

Reduce recurrence at the boundary that caused the mistake. More instructions
are not automatically better protection, and a skill is not runtime enforcement.

## Establish what actually happened

Read the relevant incident/source and current implementation or guidance.
Separate observed failure, suspected cause, historical repair and unverified
reach. Name the input/source state, producer, consumer, wrong conclusion or
action, and the consequence. A repeated symptom can have different causes.
Verify the current path before reopening an old fix queue.

Find a nearby valid case: a useful empty result, appropriate refusal, narrow
reference, harmless display truncation or correct unchanged behavior. State
what a correction must preserve. A completed applicable scan with a stated
nonzero checked population may legitimately find nothing. Zero scanned units
or missing source cannot establish that a target is clean; report the actual
state/applicability. An initialized empty store can still be a valid empty
store, not an analysis of unscanned code. Do not convert all partial results
into refusal.

## Put the protection in the right owner

Use the smallest carrier that changes the failure:

- Runtime semantics or evidence delivery: implementation and a defect-specific
  regression with valid controls and the actual serialized consumer.
- Duplicated implementation or registry/reference drift: shared owner,
  helper/generator and contract checks.
- Stable product/evidence meaning: the maintained public understanding or
  concept document, with affected public consumers corrected as authorized.
- Recurring agent judgment/routing: amend the relevant narrow skill; add one
  only for a distinct reusable job the existing skills do not cover.
- Session state, approval or deployed identity: the private execution cursor
  and dated evidence, not a skill carrying a stale release status.
- Unconfirmed opportunity: an existing intake/card with a discriminating test.

Inspect the relevant existing skill before declaring a guidance gap. If the
rule already covers the mistake, determine whether application, discoverability,
a source owner or verification failed. A concrete counterexample or application
check can help; duplicating the rule across five skills usually does not.
Preserve useful language and bounded claims instead of banning phrases globally.

Guidance work does not by itself authorize runtime repairs or publication. If a
code fix is outside the current request, record the specific required repair
and continue the authorized lesson work without claiming the defect resolved.

## Evaluate transfer, not obedience to a template

Apply the candidate to the triggering task, the valid counterexample and a
different relevant context. Observe the decision or artifact that changed.
Do not use wording/heading matches or a structural validator as proof of
judgment quality. No-change, narrower guidance and rejecting a new skill can
be successful outcomes.

For a runtime correction, preserve failure-before/repair-after evidence at the
real boundary where feasible. For guidance, distinguish author application from
independent use and comparative efficacy. An evaluator given the suspected fix
is not a cold reader; a case used to tune a revision is development evidence,
not untouched confirmation. Independent delegation needs applicable authority.

If a revision causes an overbroad refusal, unnecessary reading, new unsupported
claim or loss of a valid case, narrow or remove it. Keep only the non-obvious
guidance that survives the actual task. Do not construct a new lesson-mining,
benchmark or automatic-promotion system to maintain a small skill.

## Leave a maintainable result

Keep skill instructions self-contained where possible and route only to
relevant maintained sources. Use the available skill-creation instructions for
installation and validation. Put incident/evaluation records under `internal/`;
skills should carry reusable decisions, not private case payloads, transcripts,
temporary statuses or invented empirical guarantees.

Record the carrier, changed decision, retained counterexample, evaluation limits
and what mechanism/source change would invalidate the lesson. Update the
existing execution cursor, not a second backlog. Retire guidance when its cause
is removed or a narrower mechanism owns it. "Known error eliminated" needs
observed scope; a new instruction alone cannot support that claim.