@codeyam/codeyam-cli 0.1.0-staging.b8a55ba → 0.1.0-staging.b8b17a5

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/deprecated-prompt.md

@@ -0,0 +1,100 @@
+# Deprecated Pattern Analysis
+
+You are analyzing a codebase for **deprecated patterns** — situations where two approaches to the same problem coexist, with one fading in favor of another. These create confusion because a coding agent reading locally may follow the old pattern.
+
+## Input
+
+Read the scan data from `/tmp/codeyam-memory/deprecated-scan.json`. It contains:
+
+- `dependencies`: All npm dependency names from the project
+- `explicit_markers`: Lines containing `@deprecated`, `// legacy`, etc., with file, line number, and text
+- `git_recency`: Per-dependency counts of `recent_imports` (last 3 months) vs `old_imports` (3–12 months ago)
+
+## Analysis Steps
+
+### 1. Dependency Overlap Analysis
+
+Review the full dependency list and identify pairs or groups that serve **overlapping purposes**. Use your domain knowledge of the npm ecosystem — don't rely on name similarity alone.
+
+Common overlap categories:
+
+- **ORMs / query builders**: knex, kysely, prisma, drizzle, typeorm, sequelize, supabase-js (when used for queries)
+- **Date libraries**: moment, dayjs, date-fns, luxon
+- **HTTP clients**: axios, got, node-fetch, ky, superagent, undici
+- **State management**: redux, zustand, jotai, recoil, mobx, valtio
+- **Schema validation**: zod, yup, joi, ajv, io-ts, superstruct, valibot
+- **CSS-in-JS / styling**: styled-components, emotion, tailwind, vanilla-extract, stitches
+- **Testing**: jest, vitest, mocha, ava
+- **Bundlers**: webpack, vite, esbuild, rollup, parcel, turbopack
+- **Logging**: winston, pino, bunyan, log4js
+
+Also look for:
+
+- Internal packages that wrap the same underlying library differently
+- Old utility files alongside newer replacements
+
+### 2. Cross-Reference with Git Recency
+
+For each overlapping pair you identified, check the `git_recency` data:
+
+- Is one dependency's import count **growing** (more recent than old) while the other is **fading** (fewer recent than old)?
+- A clear growth-vs-fade pattern confirms a migration in progress.
+- If both are stable or both are growing, it may be intentional coexistence rather than a migration.
+
+### 3. Cross-Reference with Explicit Markers
+
+Check if any `@deprecated` or `// legacy` markers corroborate your dependency findings:
+
+- A marker on code that imports the fading dependency strengthens the signal
+- A marker on a wrapper/utility that abstracts one of the approaches is strong evidence
+
+### 4. Find Remaining Callsites
+
+For each confirmed deprecated pattern, use Grep to find all files still importing or using the old dependency/pattern. Count the callsites to assess migration completeness.
+
+Search patterns:
+
+```
+from ['"]<old-dep>
+require(['"]<old-dep>
+import <old-dep>
+```
+
+### 5. Assess Severity
+
+- **high**: Active migration with significant remaining old callsites (>10 files), or explicit deprecation markers present
+- **medium**: Clear trend in git recency but no explicit markers and fewer remaining callsites
+- **low**: Slight trend, possibly intentional coexistence
+
+## Output
+
+Return your findings as a JSON code block in your response, using this format:
+
+```json
+{
+  "findings": [
+    {
+      "type": "deprecated-pattern",
+      "old_pattern": "descriptive name of the old approach",
+      "new_pattern": "descriptive name of the new approach",
+      "evidence": "concise summary of the evidence (git recency numbers, markers found)",
+      "files_still_using_old": ["path/to/file1.ts", "path/to/file2.ts"],
+      "severity": "high|medium|low",
+      "suggested_rule_paths": ["src/relevant/**/*.ts"]
+    }
+  ],
+  "stats": {
+    "deps_analyzed": 0,
+    "overlapping_pairs_found": 0,
+    "confirmed_deprecated": 0
+  }
+}
+```
+
+After the JSON block, return a **brief one-paragraph summary** of your findings. Include the number of confirmed deprecated patterns and the highest-severity finding.
+
+## Important Notes
+
+- Be conservative: only flag patterns where there is clear evidence of transition, not just the presence of two similar libraries
+- Some projects intentionally use multiple tools in the same category (e.g., jest for unit tests and playwright for e2e) — that's not deprecation
+- Focus on patterns that would **mislead a coding agent** — if both approaches are valid and documented, it may not need a rule

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/detect-deprecated-patterns.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// Gathers deprecation signals from package.json, source markers, and git history.
+// Outputs structured JSON to /tmp/codeyam-memory/deprecated-scan.json
+
+import { readdir, readFile, mkdir, writeFile } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { ripgrepSearch } from '../lib/ripgrep-fallback.mjs';
+
+const OUTPUT_DIR = '/tmp/codeyam-memory';
+const OUTPUT_FILE = join(OUTPUT_DIR, 'deprecated-scan.json');
+await mkdir(OUTPUT_DIR, { recursive: true });
+
+// --- Dependency scan ---
+// Collect all dependency names from package.json files
+const allDeps = new Set();
+const packageFiles = await findFiles('.', 'package.json', ['node_modules', 'dist', '.next']);
+
+for (const pkgPath of packageFiles) {
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+    for (const key of ['dependencies', 'devDependencies']) {
+      if (pkg[key] && typeof pkg[key] === 'object') {
+        for (const dep of Object.keys(pkg[key])) allDeps.add(dep);
+      }
+    }
+  } catch {
+    // Skip unparseable package.json
+  }
+}
+
+const dependencies = [...allDeps].sort();
+
+// --- Explicit marker scan ---
+let explicitMarkers = [];
+
+const markerOutput = await ripgrepSearch(
+  '@deprecated|// legacy|// deprecated|// old approach|TODO.*deprecat|FIXME.*deprecat',
+  {
+    types: ['ts', 'js'],
+    globs: ['!node_modules', '!dist', '!build', '!.next'],
+    context: 2,
+    lineNumbers: true,
+  },
+);
+
+if (markerOutput.trim()) {
+  // Parse ripgrep output into structured entries
+  for (const line of markerOutput.split('\n')) {
+    // Match "file:line:text" (colons in file path unlikely for these repos)
+    const match = line.match(/^([^:]+):(\d+):(.*)$/);
+    if (match) {
+      explicitMarkers.push({
+        file: match[1],
+        line: parseInt(match[2], 10),
+        text: match[3].trim(),
+      });
+    }
+  }
+}
+
+// --- Git recency comparison ---
+const gitRecency = {};
+
+if (dependencies.length > 0) {
+  const recentImports = gitImports('3 months ago', undefined);
+  const oldImports = gitImports('12 months ago', '3 months ago');
+
+  for (const dep of dependencies) {
+    if (dep.length < 3) continue; // Skip short names that match too broadly
+
+    const pattern = `from ['"]${dep}`;
+    const recent = countMatches(recentImports, pattern);
+    const old = countMatches(oldImports, pattern);
+
+    if (recent > 0 || old > 0) {
+      gitRecency[dep] = { recent_imports: recent, old_imports: old };
+    }
+  }
+}
+
+// --- Assemble final output ---
+const output = {
+  dependencies,
+  explicit_markers: explicitMarkers,
+  git_recency: gitRecency,
+};
+
+await writeFile(OUTPUT_FILE, JSON.stringify(output, null, 2));
+
+console.log(`Deprecated pattern scan complete: ${OUTPUT_FILE}`);
+console.log(`  Dependencies found: ${dependencies.length}`);
+console.log(`  Explicit markers found: ${explicitMarkers.length}`);
+console.log(`  Deps with git activity: ${Object.keys(gitRecency).length}`);
+
+// --- Helpers ---
+
+async function findFiles(dir, filename, ignoreDirs) {
+  const results = [];
+  const ignoreSet = new Set(ignoreDirs);
+
+  let entries;
+  try {
+    entries = await readdir(dir, { recursive: true, withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile() || entry.name !== filename) continue;
+    const parentPath = entry.parentPath ?? entry.path; // parentPath in Node 22+
+    const parts = parentPath.split('/');
+    if (parts.some((p) => ignoreSet.has(p))) continue;
+    results.push(join(parentPath, entry.name));
+  }
+  return results;
+}
+
+function gitImports(since, until) {
+  const args = ['log', `--since=${since}`, '-p', '--', '*.ts', '*.tsx', '*.js', '*.jsx'];
+  if (until) args.splice(2, 0, `--until=${until}`);
+
+  try {
+    const output = execFileSync('git', args, {
+      maxBuffer: 100 * 1024 * 1024,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return output;
+  } catch {
+    return '';
+  }
+}
+
+function countMatches(text, pattern) {
+  const regex = new RegExp(pattern, 'g');
+  const matches = text.match(regex);
+  return matches ? matches.length : 0;
+}

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/find-exports.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Indexes the project's public API surface by finding all exports.
+// Outputs structured JSON to /tmp/codeyam-memory/exports-scan.json
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ripgrepSearch } from '../lib/ripgrep-fallback.mjs';
+
+const OUTPUT_DIR = '/tmp/codeyam-memory';
+const OUTPUT_FILE = join(OUTPUT_DIR, 'exports-scan.json');
+await mkdir(OUTPUT_DIR, { recursive: true });
+
+const exportOutput = await ripgrepSearch(
+  '^export (function|const|class|default|async function|type|interface|enum)',
+  {
+    types: ['ts', 'js'],
+    globs: ['!node_modules', '!dist', '!build', '!.next', '!*.d.ts', '!*.map'],
+    lineNumbers: true,
+  },
+);
+
+if (!exportOutput.trim()) {
+  const empty = { files: {}, stats: { total_files: 0, total_exports: 0 } };
+  await writeFile(OUTPUT_FILE, JSON.stringify(empty, null, 2));
+  console.log(`Export scan complete: ${OUTPUT_FILE} (no exports found)`);
+  process.exit(0);
+}
+
+// Parse ripgrep output and group by file
+const files = {};
+for (const line of exportOutput.split('\n')) {
+  const match = line.match(/^([^:]+):(\d+):(.*)$/);
+  if (!match) continue;
+
+  const [, file, lineNum, text] = match;
+  if (!files[file]) files[file] = [];
+  files[file].push({ line: parseInt(lineNum, 10), text: text.trim() });
+}
+
+const totalFiles = Object.keys(files).length;
+const totalExports = Object.values(files).reduce((sum, arr) => sum + arr.length, 0);
+
+const output = {
+  files,
+  stats: { total_files: totalFiles, total_exports: totalExports },
+};
+
+await writeFile(OUTPUT_FILE, JSON.stringify(output, null, 2));
+
+console.log(`Export scan complete: ${OUTPUT_FILE}`);
+console.log(`  Files with exports: ${totalFiles}`);
+console.log(`  Total exports: ${totalExports}`);

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/misleading-api-prompt.md

@@ -0,0 +1,117 @@
+# Misleading API Analysis
+
+You are analyzing a codebase for **misleading APIs** — exported functions whose names promise one thing but whose implementations do another. These are dangerous because a coding agent reading the function signature will make incorrect assumptions about behavior.
+
+## Input
+
+Read the export index from `/tmp/codeyam-memory/exports-scan.json`. It contains:
+
+- `files`: Object keyed by file path, each containing an array of `{line, text}` export declarations
+- `stats`: `total_files` and `total_exports` counts
+
+## Analysis Steps
+
+### 1. Triage by Name Pattern
+
+Scan all export names and prioritize **pure-sounding** functions — names that imply no side effects or predictable behavior:
+
+**Highest priority** (names suggesting pure computation):
+
+- `get*`, `compute*`, `calculate*`, `derive*`, `extract*`
+- `is*`, `has*`, `check*`, `can*`
+- `parse*`, `format*`, `transform*`, `convert*`
+- `to*`, `from*`, `create*` (when suggesting a factory)
+- `validate*`, `verify*`
+
+**Medium priority** (names suggesting single responsibility):
+
+- `save*`, `update*`, `delete*`, `remove*` — check for hidden secondary effects
+- `send*`, `notify*`, `emit*` — check for unexpected mutations
+- `init*`, `setup*`, `configure*` — check for non-obvious global state changes
+
+### 2. Deep Read Suspicious Exports
+
+For each pure-sounding or single-responsibility export, use the Read tool to read the **full function implementation** (not just 30 lines — read until the function ends). Look for these red flags:
+
+**Side effects in "pure" functions:**
+
+- Writes to external state (database, cache, filesystem, global variables)
+- Network calls (fetch, HTTP requests, WebSocket messages)
+- Logging that includes sensitive data or business logic decisions
+- Event emission or pub/sub publishing
+
+**Input mutation:**
+
+- Modifying objects/arrays passed as arguments (when the name doesn't suggest mutation)
+- Reassigning properties on `this` in methods that sound like getters
+
+**Silent error swallowing:**
+
+- `catch` blocks that return default values instead of throwing or propagating
+- `try/catch` around critical operations where the function signature suggests it will throw on failure
+- Optional chaining (`?.`) chains that silently return `undefined` for important data
+
+**Unexpected returns:**
+
+- Function name suggests returning one type but actually returns something different
+- `get*` functions that return `null` or `undefined` instead of throwing when the entity doesn't exist
+- Boolean-named functions (`is*`, `has*`) that return non-boolean values
+
+**Hidden coupling:**
+
+- Functions that read from or write to module-level state
+- Functions that depend on call order (must call A before B)
+- Functions that modify shared caches or memoization stores
+
+### 3. Scan Non-Pure Exports Too
+
+Quickly scan action-oriented exports (`save*`, `update*`, etc.) at a glance for **hidden secondary effects**:
+
+- `saveUser()` that also sends a welcome email
+- `deleteProject()` that also archives data elsewhere
+- `updateConfig()` that also restarts a service
+
+### 4. Count Callsites
+
+For each finding, use Grep to count how many files import or call the misleading function. More callsites = higher impact.
+
+### 5. Assess Severity
+
+- **high**: The mismatch could cause data corruption, silent failures, security issues, or affects >10 callsites
+- **medium**: The mismatch leads to unexpected behavior that would cause bugs, or affects 3–10 callsites
+- **low**: Minor naming inconsistency, affects few callsites, unlikely to cause bugs
+
+## Output
+
+Return your findings as a JSON code block in your response, using this format:
+
+```json
+{
+  "findings": [
+    {
+      "type": "misleading-api",
+      "function": "functionName",
+      "file": "path/to/file.ts",
+      "name_implies": "what the name suggests the function does",
+      "actually_does": "what it actually does (with specific line numbers for the divergent behavior)",
+      "severity": "high|medium|low",
+      "callsite_count": 0
+    }
+  ],
+  "stats": {
+    "exports_scanned": 0,
+    "deep_reads": 0,
+    "findings_count": 0
+  }
+}
+```
+
+After the JSON block, return a **brief one-paragraph summary** of your findings. Include the number of findings and the most notable misleading API discovered.
+
+## Important Notes
+
+- **Read full implementations** — don't just look at the first few lines. Side effects often live at the end of functions or in helper calls.
+- Be conservative with "low" severity findings — only flag things that would actually mislead a coding agent into writing incorrect code
+- **Skip type exports** (type, interface, enum) — these can't have behavioral mismatches
+- **Skip trivial getters** that just return a property — focus on functions with actual logic
+- When a function delegates to a helper, read the helper too if the function name implies purity but the helper name suggests side effects

package/codeyam-cli/templates/skills/codeyam-memory/scripts/lib/read-json-field.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Lightweight jq replacement for simple field lookups.
+// Usage: node read-json-field.mjs <file> '<expression>'
+// Supports: .field.subfield, .field | length
+
+import { readFile } from 'node:fs/promises';
+
+const [, , filePath, expression] = process.argv;
+
+if (!filePath || !expression) {
+  console.error('Usage: node read-json-field.mjs <file> <expression>');
+  process.exit(1);
+}
+
+try {
+  const raw = await readFile(filePath, 'utf-8');
+  const data = JSON.parse(raw);
+  const result = evaluate(data, expression);
+  console.log(typeof result === 'string' ? result : JSON.stringify(result));
+} catch (err) {
+  console.error(err.message);
+  process.exit(1);
+}
+
+function evaluate(data, expr) {
+  const trimmed = expr.trim();
+
+  // Handle pipe: ".field | length"
+  const pipeIdx = trimmed.indexOf('|');
+  if (pipeIdx !== -1) {
+    const left = trimmed.slice(0, pipeIdx).trim();
+    const right = trimmed.slice(pipeIdx + 1).trim();
+    const intermediate = resolvePath(data, left);
+
+    if (right === 'length') {
+      if (Array.isArray(intermediate)) return intermediate.length;
+      if (typeof intermediate === 'object' && intermediate !== null) return Object.keys(intermediate).length;
+      if (typeof intermediate === 'string') return intermediate.length;
+      throw new Error(`Cannot get length of ${typeof intermediate}`);
+    }
+    throw new Error(`Unsupported pipe function: ${right}`);
+  }
+
+  return resolvePath(data, trimmed);
+}
+
+function resolvePath(data, pathExpr) {
+  // Strip leading dot: ".foo.bar" -> "foo.bar"
+  const cleaned = pathExpr.startsWith('.') ? pathExpr.slice(1) : pathExpr;
+  if (cleaned === '') return data;
+
+  const keys = cleaned.split('.');
+  let current = data;
+  for (const key of keys) {
+    if (current == null || typeof current !== 'object') {
+      throw new Error(`Cannot access '${key}' on ${JSON.stringify(current)}`);
+    }
+    current = current[key];
+  }
+  return current;
+}

package/codeyam-cli/templates/skills/codeyam-memory/scripts/lib/ripgrep-fallback.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Shared ripgrep wrapper with pure-Node fallback when rg is not installed.
+
+import { execFile } from 'node:child_process';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * @param {string} pattern - Regex pattern to search for
+ * @param {object} [opts]
+ * @param {string[]} [opts.types] - File type filters, e.g. ['ts', 'js']
+ * @param {string[]} [opts.globs] - Glob filters, e.g. ['!node_modules']
+ * @param {number} [opts.context] - Lines of context around matches (-C)
+ * @param {boolean} [opts.lineNumbers] - Include line numbers (-n)
+ * @param {string} [opts.cwd] - Working directory (defaults to process.cwd())
+ * @returns {Promise<string>} ripgrep-compatible output: "file:line:text\n" lines
+ */
+export async function ripgrepSearch(pattern, opts = {}) {
+  const { types = [], globs = [], context, lineNumbers = true, cwd = process.cwd() } = opts;
+
+  try {
+    return await runRipgrep(pattern, { types, globs, context, lineNumbers, cwd });
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // rg not installed — use Node fallback
+      return nodeFallback(pattern, { types, globs, context, lineNumbers, cwd });
+    }
+    throw err;
+  }
+}
+
+function runRipgrep(pattern, { types, globs, context, lineNumbers, cwd }) {
+  return new Promise((resolve, reject) => {
+    const args = [];
+    if (lineNumbers) args.push('-n');
+    if (context != null) args.push('-C', String(context));
+    for (const t of types) args.push('--type', t);
+    for (const g of globs) args.push('--glob', g);
+    args.push(pattern, '.'); // Explicit path prevents rg from reading stdin
+
+    execFile('rg', args, { cwd, maxBuffer: 50 * 1024 * 1024 }, (err, stdout) => {
+      if (err) {
+        // Exit code 1 = no matches, 2 = error (e.g. no files searched)
+        if (err.code === 1 || err.code === 2) return resolve('');
+        // ENOENT = rg binary not found
+        if (err.code === 'ENOENT') {
+          const e = new Error('rg not found');
+          e.code = 'ENOENT';
+          return reject(e);
+        }
+        return reject(err);
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+const TYPE_EXTENSIONS = {
+  ts: ['.ts', '.tsx', '.mts', '.cts'],
+  js: ['.js', '.jsx', '.mjs', '.cjs'],
+};
+
+const DEFAULT_IGNORE = ['node_modules', 'dist', 'build', '.next', '.git'];
+
+async function nodeFallback(pattern, { types = [], globs = [], context, lineNumbers = true, cwd = process.cwd() } = {}) {
+  // Build file extension filter from types
+  const extensions = new Set();
+  for (const t of types) {
+    const exts = TYPE_EXTENSIONS[t];
+    if (exts) exts.forEach((e) => extensions.add(e));
+  }
+
+  // Parse globs for negative patterns (simple heuristic: "!dirname")
+  const ignoreDirs = new Set(DEFAULT_IGNORE);
+  for (const g of globs) {
+    if (g.startsWith('!')) ignoreDirs.add(g.slice(1));
+  }
+  // Also handle glob patterns like "!*.d.ts" and "!*.map"
+  const ignoreExtensions = new Set();
+  for (const g of globs) {
+    const m = g.match(/^!\*(\.\w+(?:\.\w+)*)$/);
+    if (m) ignoreExtensions.add(m[1]);
+  }
+
+  const regex = new RegExp(pattern);
+  const contextLines = context ?? 0;
+  const results = [];
+
+  let entries;
+  try {
+    entries = await readdir(cwd, { recursive: true });
+  } catch {
+    return '';
+  }
+
+  for (const relPath of entries) {
+    // Skip ignored directories
+    const parts = relPath.split('/');
+    if (parts.some((p) => ignoreDirs.has(p))) continue;
+
+    // Check extension filters
+    if (extensions.size > 0) {
+      const hasMatchingExt = [...extensions].some((ext) => relPath.endsWith(ext));
+      if (!hasMatchingExt) continue;
+    }
+
+    // Check ignore extensions
+    if ([...ignoreExtensions].some((ext) => relPath.endsWith(ext))) continue;
+
+    const fullPath = join(cwd, relPath);
+    let content;
+    try {
+      content = await readFile(fullPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const lines = content.split('\n');
+    const matchIndices = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (regex.test(lines[i])) matchIndices.push(i);
+    }
+
+    if (matchIndices.length === 0) continue;
+
+    if (contextLines === 0) {
+      for (const idx of matchIndices) {
+        const lineNum = idx + 1;
+        const prefix = lineNumbers ? `${relPath}:${lineNum}:` : `${relPath}:`;
+        results.push(`${prefix}${lines[idx]}`);
+      }
+    } else {
+      // With context: output blocks separated by "--"
+      const emitted = new Set();
+      for (const idx of matchIndices) {
+        const start = Math.max(0, idx - contextLines);
+        const end = Math.min(lines.length - 1, idx + contextLines);
+        for (let i = start; i <= end; i++) {
+          if (!emitted.has(i)) {
+            emitted.add(i);
+            const lineNum = i + 1;
+            const sep = i === idx ? ':' : '-';
+            const prefix = lineNumbers ? `${relPath}${sep}${lineNum}${sep}` : `${relPath}${sep}`;
+            results.push(`${prefix}${lines[i]}`);
+          }
+        }
+      }
+    }
+  }
+
+  return results.join('\n') + (results.length > 0 ? '\n' : '');
+}
+
+// Exported for testing — not part of the public API.
+export { nodeFallback as _nodeFallback };

package/codeyam-cli/templates/skills/codeyam-memory/scripts/session-mining/analyze-prompt.md

@@ -0,0 +1,46 @@
+# Session Log Analysis Prompt
+
+You are analyzing a filtered Claude Code session transcript to find instances where Claude got confused about **this specific codebase**. The transcript has been preprocessed — each line is a JSON object with `type` ("user" or "assistant"), `ts` (timestamp), and `content`.
+
+## Your Task
+
+Read the session file provided and identify moments where Claude demonstrated confusion that a `.claude/rules/` rule could have prevented.
+
+## Signal Types to Detect
+
+1. **USER_CORRECTION** — The user corrects Claude's approach, code, or assumption. Look for: "no, that's not how...", "actually...", "you need to use X not Y", "that's wrong", explicit disagreement.
+
+2. **RE_EDIT** — Claude edits the same file multiple times in quick succession, indicating the first attempt was wrong. Look for: multiple Edit/Write tool calls targeting the same file path with different content.
+
+3. **FAILED_PIVOT** — A tool call fails (test failure, bash error, type error) and Claude switches to a different approach. Look for: error in tool result followed by a new strategy in the next assistant message.
+
+4. **WRONG_ASSUMPTION** — Claude's thinking or text reveals an incorrect assumption about the codebase. Look for: statements that contradict later evidence, "I assumed...", reasoning that turns out wrong.
+
+5. **TRIBAL_KNOWLEDGE** — The user provides context Claude didn't have but needed. Look for: the user explaining how something works, why something is the way it is, historical context, non-obvious conventions.
+
+6. **APPROACH_PIVOT** — Claude abandons a call chain mid-stream and tries something completely different (without an explicit error triggering it). Look for: sudden topic/strategy shifts in assistant messages.
+
+## Rules for Reporting
+
+- **Only report codebase-specific confusion.** Generic programming mistakes (typos, syntax errors, forgetting imports for standard libraries) are NOT worth reporting.
+- **Only report findings where a `.claude/rules/` rule would prevent the confusion.** If the confusion is situational or one-off, skip it.
+- **Maximum 5 findings per session.** Prioritize the strongest, most rule-worthy signals.
+- **Be precise about file paths.** If the confusion relates to specific files, include them.
+
+## Output Format
+
+Return a JSON array (no markdown fences, no explanation outside the array). Each element:
+
+```json
+{
+  "signal": "USER_CORRECTION | RE_EDIT | FAILED_PIVOT | WRONG_ASSUMPTION | TRIBAL_KNOWLEDGE | APPROACH_PIVOT",
+  "summary": "One sentence describing what went wrong",
+  "evidence": "Brief quote or paraphrase from the session proving this happened",
+  "file_path": "path/to/relevant/file.ts or null if not file-specific",
+  "topic": "kebab-case-topic-label",
+  "rule_worthy": true,
+  "rule_worthy_reason": "Why a rule would prevent this from recurring"
+}
+```
+
+If the session contains no codebase-specific confusion worth documenting, return an empty array: `[]`

package/codeyam-cli/templates/skills/codeyam-memory/scripts/session-mining/cleanup.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Removes cached preprocessed session files.
+
+import { rm } from 'node:fs/promises';
+
+const OUTPUT_DIR = '/tmp/cc-session-analysis';
+
+try {
+  await rm(OUTPUT_DIR, { recursive: true, force: true });
+  console.log(`Cleaned up ${OUTPUT_DIR}`);
+} catch {
+  console.log(`Nothing to clean up (${OUTPUT_DIR} does not exist)`);
+}