gitmem-mcp 1.2.2 → 1.3.0

package/bin/uninstall.js

@@ -28,6 +28,35 @@ const deleteAll = args.includes("--all");
 const clientIdx = args.indexOf("--client");
 const clientFlag = clientIdx !== -1 ? args[clientIdx + 1]?.toLowerCase() : null;
 
+// ── Colors (brand-matched to init wizard) ──
+
+const _color =
+  !process.env.NO_COLOR &&
+  !process.env.GITMEM_NO_COLOR &&
+  process.stdout.isTTY;
+
+const C = {
+  reset: _color ? "\x1b[0m" : "",
+  bold:  _color ? "\x1b[1m" : "",
+  dim:   _color ? "\x1b[2m" : "",
+  red:   _color ? "\x1b[31m" : "",
+  green: _color ? "\x1b[32m" : "",
+  yellow: _color ? "\x1b[33m" : "",
+};
+
+const RIPPLE = `${C.dim}(${C.reset}${C.red}(${C.reset}${C.bold}\u25cf${C.reset}${C.red})${C.reset}${C.dim})${C.reset}`;
+const PRODUCT = `${RIPPLE} ${C.red}gitmem${C.reset}`;
+const CHECK = `${C.bold}\u2714${C.reset}`;
+const SKIP = `${C.dim}\u00b7${C.reset}`;
+
+let actionsTaken = 0;
+
+function log(icon, msg, extra) {
+  if (icon === CHECK) actionsTaken++;
+  const suffix = extra ? ` ${C.dim}${extra}${C.reset}` : "";
+  console.log(`${icon} ${msg}${suffix}`);
+}
+
 // ── Client Configuration ──
 
 const CLIENT_CONFIGS = {
@@ -125,13 +154,11 @@ function writeJson(path, data) {
 }
 
 function isGitmemHook(entry) {
-  // Claude Code format: entry.hooks is an array of {command: "..."}
   if (entry.hooks && Array.isArray(entry.hooks)) {
     return entry.hooks.some(
       (h) => typeof h.command === "string" && h.command.includes("gitmem")
     );
   }
-  // Cursor format: entry itself has {command: "..."}
   if (typeof entry.command === "string") {
     return entry.command.includes("gitmem");
   }
@@ -142,49 +169,47 @@ function isGitmemHook(entry) {
 
 function stepInstructions() {
   if (!existsSync(cc.instructionsFile)) {
-    console.log(`  No ${cc.instructionsName} found. Skipping.`);
+    log(SKIP, `No ${cc.instructionsName} found`);
     return;
   }
 
   let content = readFileSync(cc.instructionsFile, "utf-8");
 
   if (!content.includes(cc.startMarker)) {
-    console.log(`  No gitmem section in ${cc.instructionsName}. Skipping.`);
+    log(SKIP, `No gitmem section in ${cc.instructionsName}`);
     return;
   }
 
   const startIdx = content.indexOf(cc.startMarker);
   const endIdx = content.indexOf(cc.endMarker);
   if (startIdx === -1 || endIdx === -1) {
-    console.log(`  Malformed gitmem markers in ${cc.instructionsName}. Skipping.`);
+    log(SKIP, `Malformed gitmem markers in ${cc.instructionsName}`);
     return;
   }
 
-  // Remove the block including markers and surrounding whitespace
   const before = content.slice(0, startIdx).trimEnd();
   const after = content.slice(endIdx + cc.endMarker.length).trimStart();
-
   const result = before + (before && after ? "\n\n" : "") + after;
 
   if (result.trim() === "") {
     rmSync(cc.instructionsFile);
-    console.log(`  Removed ${cc.instructionsName} (was gitmem-only)`);
+    log(CHECK, `Removed ${cc.instructionsName}`, "(was gitmem-only)");
   } else {
     writeFileSync(cc.instructionsFile, result.trimEnd() + "\n");
-    console.log(`  Stripped gitmem section from ${cc.instructionsName}`);
+    log(CHECK, `Stripped gitmem section from ${cc.instructionsName}`, "(your content preserved)");
   }
 }
 
 function stepMcpJson() {
   const config = readJson(cc.mcpConfigPath);
   if (!config?.mcpServers) {
-    console.log(`  No ${cc.mcpConfigName} found. Skipping.`);
+    log(SKIP, `No ${cc.mcpConfigName} found`);
     return;
   }
 
   const had = !!config.mcpServers.gitmem || !!config.mcpServers["gitmem-mcp"];
   if (!had) {
-    console.log(`  No gitmem in ${cc.mcpConfigName}. Skipping.`);
+    log(SKIP, `No gitmem in ${cc.mcpConfigName}`);
     return;
   }
 
@@ -193,9 +218,11 @@ function stepMcpJson() {
 
   const remaining = Object.keys(config.mcpServers).length;
   writeJson(cc.mcpConfigPath, config);
-  console.log(
-    `  Removed gitmem server (${remaining} other server${remaining !== 1 ? "s" : ""} preserved)`
-  );
+  if (remaining > 0) {
+    log(CHECK, `Removed gitmem server`, `(${remaining} other server${remaining !== 1 ? "s" : ""} preserved)`);
+  } else {
+    log(CHECK, `Removed gitmem server from ${cc.mcpConfigName}`);
+  }
 }
 
 function stepHooks() {
@@ -208,7 +235,7 @@ function stepHooks() {
 function stepHooksClaude() {
   const settings = readJson(cc.settingsFile);
   if (!settings?.hooks) {
-    console.log("  No hooks in .claude/settings.json. Skipping.");
+    log(SKIP, "No hooks in .claude/settings.json");
     return;
   }
 
@@ -232,7 +259,7 @@ function stepHooksClaude() {
   }
 
   if (removed === 0) {
-    console.log("  No gitmem hooks found. Skipping.");
+    log(SKIP, "No gitmem hooks found");
     return;
   }
 
@@ -243,18 +270,17 @@ function stepHooksClaude() {
   }
 
   writeJson(cc.settingsFile, settings);
-  console.log(
-    `  Removed gitmem hooks` +
-      (preserved > 0
-        ? ` (${preserved} other hook${preserved !== 1 ? "s" : ""} preserved)`
-        : "")
-  );
+  if (preserved > 0) {
+    log(CHECK, "Removed automatic memory hooks", `(${preserved} other hook${preserved !== 1 ? "s" : ""} preserved)`);
+  } else {
+    log(CHECK, "Removed automatic memory hooks");
+  }
 }
 
 function stepHooksCursor() {
   const config = readJson(cc.hooksFile);
   if (!config?.hooks) {
-    console.log(`  No hooks in ${cc.hooksFileName}. Skipping.`);
+    log(SKIP, `No hooks in ${cc.hooksFileName}`);
     return;
   }
 
@@ -278,7 +304,7 @@ function stepHooksCursor() {
   }
 
   if (removed === 0) {
-    console.log("  No gitmem hooks found. Skipping.");
+    log(SKIP, "No gitmem hooks found");
     return;
   }
 
@@ -289,38 +315,36 @@ function stepHooksCursor() {
   }
 
   writeJson(cc.hooksFile, config);
-  console.log(
-    `  Removed gitmem hooks` +
-      (preserved > 0
-        ? ` (${preserved} other hook${preserved !== 1 ? "s" : ""} preserved)`
-        : "")
-  );
+  if (preserved > 0) {
+    log(CHECK, "Removed automatic memory hooks", `(${preserved} other hook${preserved !== 1 ? "s" : ""} preserved)`);
+  } else {
+    log(CHECK, "Removed automatic memory hooks");
+  }
 }
 
 function stepPermissions() {
   if (!cc.hasPermissions) {
-    console.log(`  Not needed for ${cc.name}. Skipping.`);
+    log(SKIP, `Not needed for ${cc.name}`);
     return;
   }
 
   const settings = readJson(cc.settingsFile);
   const allow = settings?.permissions?.allow;
   if (!Array.isArray(allow)) {
-    console.log("  No permissions in .claude/settings.json. Skipping.");
+    log(SKIP, "No permissions in .claude/settings.json");
     return;
   }
 
   const pattern = "mcp__gitmem__*";
   const idx = allow.indexOf(pattern);
   if (idx === -1) {
-    console.log("  No gitmem permissions found. Skipping.");
+    log(SKIP, "No gitmem permissions found");
     return;
   }
 
   allow.splice(idx, 1);
   settings.permissions.allow = allow;
 
-  // Clean up empty permissions
   if (allow.length === 0) {
     delete settings.permissions.allow;
   }
@@ -332,31 +356,26 @@ function stepPermissions() {
   }
 
   writeJson(cc.settingsFile, settings);
-  console.log("  Removed mcp__gitmem__* from permissions.allow");
+  log(CHECK, "Removed tool permissions");
 }
 
 async function stepGitmemDir() {
   if (!existsSync(gitmemDir)) {
-    console.log("  No .gitmem/ directory. Skipping.");
+    log(SKIP, "No .gitmem/ directory");
     return;
   }
 
   if (deleteAll) {
     rmSync(gitmemDir, { recursive: true, force: true });
-    console.log("  Deleted .gitmem/ directory");
+    log(CHECK, "Deleted .gitmem/ directory");
     return;
   }
 
-  console.log(
-    "  This contains your memory data (scars, sessions, decisions)."
-  );
-
-  // Default to No for data deletion
-  if (await confirm("Delete .gitmem/?", false)) {
-    rmSync(gitmemDir, { recursive: true, force: true });
-    console.log("  Deleted .gitmem/ directory");
+  if (await confirm("Keep .gitmem/ memory data for future use?", true)) {
+    log(CHECK, ".gitmem/ preserved — your memories will be here if you reinstall");
   } else {
-    console.log("  Skipped — .gitmem/ preserved.");
+    rmSync(gitmemDir, { recursive: true, force: true });
+    log(CHECK, "Deleted .gitmem/ directory");
   }
 }
 
@@ -366,58 +385,38 @@ function stepGitignore() {
   let content = readFileSync(gitignorePath, "utf-8");
   if (!content.includes(".gitmem/")) return;
 
-  // Remove the .gitmem/ line
   const lines = content.split("\n");
   const filtered = lines.filter((line) => line.trim() !== ".gitmem/");
   writeFileSync(gitignorePath, filtered.join("\n"));
+  log(CHECK, "Cleaned .gitignore");
 }
 
 // ── Main ──
 
 async function main() {
+  const pkg = readJson(join(__dirname, "..", "package.json"));
+  const version = pkg?.version || "1.0.0";
+
   console.log("");
-  console.log(`  gitmem — Uninstall (${cc.name})`);
-  if (clientFlag) {
-    console.log(`  (client: ${client} — via --client flag)`);
-  } else {
-    console.log(`  (client: ${client} — auto-detected)`);
-  }
+  console.log(`${PRODUCT} \u2500\u2500 uninstall v${version}`);
+  console.log(`${C.dim}Removing gitmem from ${cc.name}${clientFlag ? "" : " (auto-detected)"}${C.reset}`);
   console.log("");
 
-  const stepCount = cc.hasPermissions ? 5 : 4;
-  let step = 1;
-
-  console.log(`  Step ${step}/${stepCount} — Remove gitmem section from ${cc.instructionsName}`);
   stepInstructions();
-  console.log("");
-  step++;
-
-  console.log(`  Step ${step}/${stepCount} — Remove gitmem from ${cc.mcpConfigName}`);
   stepMcpJson();
-  console.log("");
-  step++;
-
-  const hooksTarget = cc.hooksInSettings ? ".claude/settings.json" : cc.hooksFileName;
-  console.log(`  Step ${step}/${stepCount} — Remove gitmem hooks from ${hooksTarget}`);
   stepHooks();
-  console.log("");
-  step++;
-
-  if (cc.hasPermissions) {
-    console.log(`  Step ${step}/${stepCount} — Remove gitmem permissions from .claude/settings.json`);
-    stepPermissions();
-    console.log("");
-    step++;
-  }
-
-  console.log(`  Step ${step}/${stepCount} — Delete .gitmem/ directory?`);
+  stepPermissions();
   await stepGitmemDir();
-
-  // Also clean .gitignore entry
   stepGitignore();
 
   console.log("");
-  console.log("  Uninstall complete.");
+  if (actionsTaken > 0) {
+    console.log(`${C.dim}gitmem-mcp has been removed.${C.reset}`);
+    console.log(`${C.dim}Reinstall anytime: ${C.reset}${C.red}npx gitmem-mcp init${C.reset}`);
+  } else {
+    console.log(`${C.dim}gitmem-mcp is not installed in this project.${C.reset}`);
+    console.log(`${C.dim}Install: ${C.reset}${C.red}npx gitmem-mcp init${C.reset}`);
+  }
   console.log("");
 
   if (rl) rl.close();

package/dist/services/enforcement.js

@@ -10,7 +10,7 @@
  * - Universal: works in ALL MCP clients, no IDE hooks needed
  * - Lightweight: pure in-memory checks, no I/O
  */
-import { getCurrentSession, hasUnconfirmedScars, getSurfacedScars } from "./session-state.js";
+import { getCurrentSession, hasUnconfirmedScars, getSurfacedScars, isRecallCalled } from "./session-state.js";
 /**
  * Tools that require an active session to function properly.
  * Read-only/administrative tools are excluded.
@@ -107,19 +107,17 @@ export function checkEnforcement(toolName) {
         };
     }
     // Check 3: No recall before consequential action
-    if (CONSEQUENTIAL_TOOLS.has(toolName)) {
-        const recallScars = getSurfacedScars().filter(s => s.source === "recall");
-        if (recallScars.length === 0) {
-            return {
-                warning: [
-                    "--- gitmem enforcement ---",
-                    "No recall() was run this session before this action.",
-                    "Consider calling recall() first to check for relevant institutional memory.",
-                    "Past mistakes and patterns may prevent repeating known issues.",
-                    "---",
-                ].join("\n"),
-            };
-        }
+    // Uses recallCalled boolean to avoid false positives when recall returns 0 scars
+    if (CONSEQUENTIAL_TOOLS.has(toolName) && !isRecallCalled()) {
+        return {
+            warning: [
+                "--- gitmem enforcement ---",
+                "No recall() was run this session before this action.",
+                "Consider calling recall() first to check for relevant institutional memory.",
+                "Past mistakes and patterns may prevent repeating known issues.",
+                "---",
+            ].join("\n"),
+        };
     }
     return { warning: null };
 }

package/dist/services/session-state.d.ts

@@ -18,6 +18,7 @@ interface SessionContext {
     agent?: string;
     project?: string;
     startedAt: Date;
+    recallCalled: boolean;
     surfacedScars: SurfacedScar[];
     confirmations: ScarConfirmation[];
     reflections: ScarReflection[];
@@ -29,7 +30,7 @@ interface SessionContext {
  * Set the current active session
  * Called by session_start
  */
-export declare function setCurrentSession(context: Omit<SessionContext, 'surfacedScars' | 'confirmations' | 'reflections' | 'observations' | 'children' | 'threads'> & {
+export declare function setCurrentSession(context: Omit<SessionContext, 'recallCalled' | 'surfacedScars' | 'confirmations' | 'reflections' | 'observations' | 'children' | 'threads'> & {
     surfacedScars?: SurfacedScar[];
     observations?: Observation[];
     children?: SessionChild[];
@@ -54,6 +55,16 @@ export declare function getProject(): string | null;
  * Check if currently working on a Linear issue
  */
 export declare function hasActiveIssue(): boolean;
+/**
+ * Mark that recall() was called this session (independent of whether it returned scars).
+ * Called by recall tool before any early return.
+ */
+export declare function setRecallCalled(): void;
+/**
+ * Check if recall() was called this session.
+ * Used by enforcement to avoid false positives when recall returns 0 scars.
+ */
+export declare function isRecallCalled(): boolean;
 /**
  * Add surfaced scars to tracking (deduplicates by scar_id)
  * Called by session_start and recall when scars are surfaced.

package/dist/services/session-state.js

@@ -20,6 +20,7 @@ let currentSession = null;
 export function setCurrentSession(context) {
     currentSession = {
         ...context,
+        recallCalled: false,
         surfacedScars: context.surfacedScars || [],
         confirmations: [],
         reflections: [],
@@ -59,6 +60,23 @@ export function getProject() {
 export function hasActiveIssue() {
     return !!(currentSession?.linearIssue);
 }
+/**
+ * Mark that recall() was called this session (independent of whether it returned scars).
+ * Called by recall tool before any early return.
+ */
+export function setRecallCalled() {
+    if (currentSession) {
+        currentSession.recallCalled = true;
+        console.error("[session-state] recall() marked as called");
+    }
+}
+/**
+ * Check if recall() was called this session.
+ * Used by enforcement to avoid false positives when recall returns 0 scars.
+ */
+export function isRecallCalled() {
+    return currentSession?.recallCalled ?? false;
+}
 /**
  * Add surfaced scars to tracking (deduplicates by scar_id)
  * Called by session_start and recall when scars are surfaced.

package/dist/tools/recall.d.ts

@@ -47,6 +47,7 @@ interface FormattedScar {
     applies_when: string[];
     source_issue?: string;
     similarity: number;
+    is_starter?: boolean;
     required_verification?: RequiredVerification;
     variant_info?: ScarWithVariant;
     why_this_matters?: string;

package/dist/tools/recall.js

@@ -19,7 +19,7 @@ import { getProject } from "../services/session-state.js";
 import { getStorage } from "../services/storage.js";
 import { Timer, recordMetrics, buildPerformanceData, buildComponentPerformance, calculateContextBytes, } from "../services/metrics.js";
 import { getOrAssignVariant, formatVariantEnforcement, } from "../services/variant-assignment.js";
-import { addSurfacedScars, getCurrentSession } from "../services/session-state.js";
+import { addSurfacedScars, getCurrentSession, setRecallCalled } from "../services/session-state.js";
 import { getAgentIdentity } from "../services/agent-detection.js";
 import { v4 as uuidv4 } from "uuid";
 import * as fs from "fs";
@@ -36,12 +36,18 @@ function formatResponse(scars, plan, dismissals) {
 
 No past lessons match this plan closely enough. Scars accumulate as you work — create learnings during session close to build institutional memory.`;
     }
+    // First-recall welcome: all results are starter scars
+    const allStarter = scars.length > 0 && scars.every((s) => s.is_starter === true);
     // Check if any scars have required_verification (blocking gates)
     const scarsWithVerification = scars.filter((s) => s.required_verification?.blocking);
     const lines = [
         formatNudgeHeader(scars.length),
         "",
     ];
+    if (allStarter) {
+        lines.push(`${dimText("This is your first recall — results will get more relevant as you add your own lessons from real experience.")}`);
+        lines.push("");
+    }
     // Display blocking verification requirements FIRST and prominently
     if (scarsWithVerification.length > 0) {
         lines.push(`${ANSI.yellow}VERIFICATION REQUIRED${ANSI.reset}`);
@@ -161,6 +167,9 @@ export async function recall(params) {
     const project = params.project || getProject() || "default";
     const matchCount = params.match_count || 3;
     const issueId = params.issue_id; // For variant assignment
+    // Mark recall as called BEFORE any search — prevents enforcement false positives
+    // when recall returns 0 matching scars
+    setRecallCalled();
     // Similarity threshold — suppress weak matches
     // Pro tier: 0.45 calibrated from UX audit (66% N_A rate at 0.35, APPLYING avg 0.55, N_A avg 0.51)
     // Free tier: 0.4 (BM25 scores are relative — top result always 1.0)
@@ -182,6 +191,7 @@ export async function recall(params) {
                 counter_arguments: scar.counter_arguments || [],
                 applies_when: [],
                 similarity: scar.similarity || 0,
+                is_starter: scar.is_starter,
             }))
                 // Filter below threshold
                 .filter((scar) => scar.similarity >= similarityThreshold);
@@ -342,6 +352,7 @@ export async function recall(params) {
             applies_when: scar.applies_when || [],
             source_issue: scar.source_linear_issue,
             similarity: scar.similarity || 0,
+            is_starter: scar.is_starter,
             required_verification: scar.required_verification,
             variant_info: variantResults.get(scar.id),
             // LLM-cooperative enforcement fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitmem-mcp",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "mcpName": "io.github.gitmem-dev/gitmem",
   "description": "Institutional memory for AI coding agents. Memory that compounds.",
   "type": "module",

package/schema/starter-scars.json

@@ -1,6 +1,6 @@
 [
   {
-    "id": "00000000-0000-0000-0000-000000000002",
+    "id": "81fe2d44-24ae-4946-a063-d4ea3a12a71a",
     "learning_type": "scar",
     "title": "Done != Deployed != Verified Working",
     "description": "Code being 'done' (merged) doesn't mean it's deployed, and being deployed doesn't mean it's working correctly in production. The full loop is: merge → deploy → verify the feature works end-to-end in the target environment. Skipping verification leads to silent failures.",
@@ -18,7 +18,7 @@
     "created_at": "2026-01-01T00:00:00Z"
   },
   {
-    "id": "00000000-0000-0000-0000-000000000004",
+    "id": "07c7f9d3-1336-4fef-81da-af7c97590ab9",
     "learning_type": "scar",
     "title": "Database Migration Without Rollback Plan",
     "description": "Running database migrations without a tested rollback plan risks data loss or extended downtime. Destructive migrations (dropping columns, changing types) are especially dangerous. Always write and test the down migration before running the up migration in production.",
@@ -36,7 +36,7 @@
     "created_at": "2026-01-01T00:00:00Z"
   },
   {
-    "id": "00000000-0000-0000-0000-000000000010",
+    "id": "33996174-a7f4-42f5-81ac-f601e566cc5a",
     "learning_type": "scar",
     "title": "Silent Error Swallowing Hides Real Failures",
     "description": "Empty catch blocks and generic error handlers that log but don't surface errors lead to silent failures. The system appears to work while data is lost or corrupted. At minimum, log errors with enough context to diagnose the issue. Better: fail visibly so problems are caught early.",
@@ -52,5 +52,77 @@
     "project": "default",
     "source_date": "2026-01-01",
     "created_at": "2026-01-01T00:00:00Z"
+  },
+  {
+    "id": "726c03d4-8962-4b0f-89a2-ea1cd0b223aa",
+    "learning_type": "scar",
+    "title": "Untested Code Passes By Coincidence",
+    "description": "Code without tests may appear to work because the happy path succeeds, but untested edge cases silently fail. Tests that don't exist can't catch regressions. 'It works on my machine' is not a test — write assertions for the behavior you expect, especially boundary conditions and error paths.",
+    "severity": "high",
+    "scar_type": "process",
+    "is_starter": true,
+    "counter_arguments": [
+      "The code is simple enough that tests aren't needed — but simple code gets modified later and regressions appear without test coverage",
+      "Manual testing is sufficient for this — but manual tests don't run automatically and get skipped under time pressure"
+    ],
+    "keywords": ["testing", "coverage", "regression", "assertions", "edge-cases"],
+    "domain": ["testing", "quality"],
+    "project": "default",
+    "source_date": "2026-01-01",
+    "created_at": "2026-01-01T00:00:00Z"
+  },
+  {
+    "id": "8a376e29-dc8d-49a7-b840-28643086e90a",
+    "learning_type": "scar",
+    "title": "Environment Config Drift Between Local and Production",
+    "description": "Environment variables, feature flags, and configuration that differ between local dev and production cause bugs that only appear after deployment. The fix works locally but breaks in prod because of a missing env var, different API URL, or stricter security policy. Keep a canonical list of all config, validate it at startup, and test with production-like config.",
+    "severity": "high",
+    "scar_type": "operational",
+    "is_starter": true,
+    "counter_arguments": [
+      "We use the same .env file everywhere — but .env files drift silently and new variables get added locally without updating production",
+      "Our staging environment matches production — but staging configs still diverge over time without automated drift detection"
+    ],
+    "keywords": ["environment", "config", "env-vars", "production", "deployment", "drift"],
+    "domain": ["config", "deployment"],
+    "project": "default",
+    "source_date": "2026-01-01",
+    "created_at": "2026-01-01T00:00:00Z"
+  },
+  {
+    "id": "b6a9ac29-25ba-4667-9fed-0ada98dd588e",
+    "learning_type": "scar",
+    "title": "Changing Dependencies Without Checking Breaking Changes",
+    "description": "Upgrading or adding dependencies without reading the changelog introduces breaking changes that surface later as mysterious failures. Semver violations are common — a minor version bump can still break your code. Always read the changelog, check for breaking changes, and run your test suite after any dependency change.",
+    "severity": "medium",
+    "scar_type": "process",
+    "is_starter": true,
+    "counter_arguments": [
+      "It's just a patch version so it should be safe — but semver is a social contract, not a guarantee, and patch releases do contain breaking changes",
+      "Our lockfile protects us — but lockfiles only help if everyone uses them consistently and CI doesn't do fresh installs"
+    ],
+    "keywords": ["dependencies", "npm", "upgrade", "breaking-changes", "changelog", "semver"],
+    "domain": ["dependencies", "maintenance"],
+    "project": "default",
+    "source_date": "2026-01-01",
+    "created_at": "2026-01-01T00:00:00Z"
+  },
+  {
+    "id": "5db0ffc7-e6d8-48bc-aa23-fce7fd8eaadb",
+    "learning_type": "scar",
+    "title": "Fixing Symptoms Instead of Root Causes",
+    "description": "Adding workarounds, special cases, or retry logic to mask a bug treats the symptom while the root cause remains. The workaround becomes tech debt that makes the real fix harder to find later. Before writing a fix, trace the execution path to understand WHY the failure happens, not just WHERE it happens.",
+    "severity": "high",
+    "scar_type": "process",
+    "is_starter": true,
+    "counter_arguments": [
+      "We need a quick fix now and can investigate later — but 'later' rarely comes and the workaround becomes permanent",
+      "The root cause is in a system we don't control — but understanding the root cause still helps write a better workaround with clear documentation"
+    ],
+    "keywords": ["debugging", "root-cause", "workaround", "tech-debt", "symptoms"],
+    "domain": ["debugging", "engineering"],
+    "project": "default",
+    "source_date": "2026-01-01",
+    "created_at": "2026-01-01T00:00:00Z"
   }
 ]