Learning From Corrections

{{ACTIVE_RULES}}

Learning From Corrections

Overview

Closes the feedback loop from manual Figma edits back into Bridge's knowledge base. Diffs the live Figma state against the saved snapshot, classifies each correction as a LEARNING (DS-compliant → persisted) or a FLAG (hardcoded → surfaced), updates learnings.json, and auto-patches the active recipe when eligible.

When to Use

Invoke when the user:

• says "I adjusted it", "I fixed it in Figma", "fix", "correct", or "learn from what I changed"
• has an active CSpec in specs/active/ with a snapshot

Do NOT use if:

• there is no active CSpec — the user should make first (use generating-figma-design)
• the user wants to start fresh — use generating-figma-design with a new description
• the user wants to ship — use shipping-and-archiving

Procedure

Before starting, load:

• references/transport-adapter.md (repo-root) — for Figma state re-read
• references/compiler-reference.md (repo-root) — for scene graph recompile (if re-executing after fix)

Prerequisites

• Active CSpec in specs/active/ (abort if missing: "No active CSpec. Run: make <description>")
• Snapshot file exists at specs/active/{name}-snapshot.json (abort if missing: "No snapshot found. The design must have been generated with make. Run make first.")
• Figma MCP transport available (see references/transport-adapter.md (repo-root) Section F)

1. Load artifacts

• Read the active CSpec from specs/active/{name}.cspec.yaml
• Read the snapshot from specs/active/{name}-snapshot.json
• Read existing learnings from knowledge-base/learnings.json (create empty structure if file doesn't exist)
• Load knowledge-base/registries/variables.json for token resolution

2. Re-extract current Figma state

Run a node tree extraction script via Plugin API execution, using the rootNodeId and fileKey from the snapshot's meta.

Console transport:

figma_execute({
  code: "return (async function() { ... extraction script with rootNodeId ... })();"
})

Official transport:

use_figma({
  fileKey: "{fileKey}",
  description: "Re-extract node tree for fix diff",
  code: "... extraction script without IIFE wrapper ..."
})

The extraction script walks the node tree and captures: id, name, type, layoutMode, itemSpacing, padding*, cornerRadius, fills, boundVariables, width, height, componentKey, children.

3. Diff snapshot vs current state

Compare the two JSON trees in context. Claude performs this comparison directly.

Match strategy:

• Match nodes by id (stable across edits)
• For each matched node, compare:
  • Layout: layoutMode, itemSpacing, paddingTop/Bottom/Left/Right
  • Visual: cornerRadius, fills, boundVariables
  • Size: width, height
  • Component: componentKey (detect swapped components)
• Detect added nodes (present in current, absent in snapshot)
• Detect removed nodes (present in snapshot, absent in current)
• Detect property changes (same node, different values)

Ignore:

• Pure name changes (layer renaming)
• Position changes (x, y) unless they indicate a structural move (re-parenting)

4. Classify changes

For each detected change:

Does the new value use a DS token (bound variable)?
  -> YES: Classify as LEARNING (DS-compliant correction)
  -> NO (hardcoded hex, raw px, unbound): Classify as FLAG (needs attention)

Token resolution: Check boundVariables in the current tree. If the property has a bound variable ID, resolve it against registries/variables.json to get the token name.

5. Save learnings

For each LEARNING-classified change:

1. Determine context:

   • screenType: from the CSpec's meta.pattern or intent
   • component: nearest component ancestor name, or the node's own name if it's a component instance
   • section: parent frame name (e.g., "header", "content", "sidebar")

2. Check for existing learning: Search learnings.json for a learning with matching context + change.property + change.to.token

   • If found: increment signals, append to history
   • If not found: create new learning entry

3. Generate rule: Write a human-readable rule describing the preference (e.g., "For settings screens, cards use spacing/medium (not large)")

4. Check promotion: After updating signals, check if any contextual learning qualifies for global promotion:

   • signals >= 3
   • Observations from >= 2 different screenType values
   • No contradiction (same property pointing to different tokens in different learnings)