Rc Lessons

Loop Lessons

The learning layer that makes RC loops safe to repeat. Every time verification catches a defect, the reason it slipped through is captured as a grounded lesson; before the next task or roadmap phase is planned, the corroborated lessons are loaded as guidance. A one-off is never trusted — a lesson is only promoted after it recurs across two distinct features, and is quarantined if it ever fails when applied.

The script owns the bookkeeping. IDs, recurrence counting, promotion, quarantine, and pruning are mechanical and rot when done by hand, so they live in scripts/lessons.mjs (deterministic, dependency-free) — never re-implement them in prose or edit the store by hand.

• Canonical store: .rc/lessons.json (machine-owned — do not hand-edit)
• Rendered playbook: .rc/LESSONS.md (regenerated on every write)

Invoke the script via the plugin root:

node "$CLAUDE_PLUGIN_ROOT/scripts/lessons.mjs"  --root  [flags]

--root is the directory that contains .rc/ (default .). Run --selftest to verify the lifecycle offline.

When to RECORD a lesson (write)

Record only at a verification/review boundary, and only with real grounding — a lesson with no file:line / AC id / mutant id / SPEC_DEVIATION reference is an opinion, and the script refuses it. Record when a rc-execute-task / rc-final-verify / rc-code-review / rc-review-round pass catches:

| Signal | Use when | | --- | --- | | ac_gap | An acceptance criterion had no test / was not covered. | | surviving_mutant | A discrimination/adversarial check survived — the test was too weak. | | spec_precision_gap | The spec did not define a precise enough outcome. | | spec_deviation | The implementation diverged from spec/design (SPEC_DEVIATION). | | gate_fail | A build-level gate failed (build / lint / typecheck / test). |

node "$CLAUDE_PLUGIN_ROOT/scripts/lessons.mjs" add \
  --feature  \
  --signal  \
  --source "" \
  --text "" \
  --scope ""

Phrase --text tersely and canonically — dedup is exact-after-normalization, so two wordings of the same lesson only merge (and thus promote) if they normalize alike. State the fix, not the incident: "Assert world x/z per placement, not just prop count", not "the environment test failed again".

When to LOAD lessons (read)

Load confirmed lessons before planning — at the start of rc-create-tasks, rc-create-prd technical clarification, a rc-roadmap phase plan, or the Planner step of a loop. Confirmed lessons are corroborated guidance; candidates are tracked but not trusted, so do not load them as instructions.

node "$CLAUDE_PLUGIN_ROOT/scripts/lessons.mjs" list --root             # confirmed only
node "$CLAUDE_PLUGIN_ROOT/scripts/lessons.mjs" list --root  --scope server/room
node "$CLAUDE_PLUGIN_ROOT/scripts/lessons.mjs" status --root 

Apply a confirmed lesson as a planning/design constraint for the matching scope. If applying a lesson leads to a failure, penalize it so it heads toward quarantine instead of misleading the next loop:

node "$CLAUDE_PLUGIN_ROOT/scripts/lessons.mjs" penalize --root  --id L-007

Rules

• Grounding or nothing. No --source, no lesson. The script enforces this; do not work around it.
• Never hand-edit .rc/lessons.json or .rc/LESSONS.md — the next script write overwrites them.
• One lesson = one terse sentence. Not a paragraph, not a stack trace, not the task spec.
• Confirmed guides, candidates observe. Only load confirmed at plan/design time.
• Distinct-feature promotion. --feature is the slug the signal came from; re-recording within

the same feature accrues evidence but never promotes.

Not this skill

• User corrections / workflow trigger→action learnings, cross-session → rc-memory (.rc/memory/LEARNINGS.md).
• Per-task working notes, decisions, handoff within one run → rc-workflow-memory (.rc/tasks//memory/).
• On-demand "what did I learn from this diff?" reflection (no store) → rc-lesson-learned.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rodolfochicone
• Source: rodolfochicone/rc-project
• License: MIT
• Homepage: https://rodolfochicone.dev

Install and usage instructions live in the source repository linked above.