@codeyam/codeyam-cli 0.1.7 → 0.1.9

package/codeyam-cli/templates/{codeyam-memory.md → skills/codeyam-memory/SKILL.md}

@@ -208,6 +208,215 @@ Prioritize areas with stronger confusion signals:
 
 Focus your documentation efforts on areas with the highest confusion scores.
 
+Holistic source analysis signals (from the Holistic Source Analysis phase below) also feed into this scoring. Session mining signals (from the Session Log Mining phase below) feed into this same table.
+
+---
+
+## Phase 3B: Analysis Sizing & Menu
+
+Before running the expensive LLM-powered analysis phases, run the fast extraction scripts to gather sizing metrics and let the user choose which phases to run.
+
+### Step 1: Run fast extraction scripts (concurrent)
+
+Clear stale data from any previous run, then run all three scripts in parallel:
+
+```bash
+rm -rf /tmp/codeyam-memory/ /tmp/cc-session-analysis/
+```
+
+```bash
+node .claude/skills/codeyam-memory/scripts/holistic-analysis/detect-deprecated-patterns.mjs
+```
+
+```bash
+node .claude/skills/codeyam-memory/scripts/holistic-analysis/find-exports.mjs
+```
+
+```bash
+node .claude/skills/codeyam-memory/scripts/session-mining/preprocess.mjs 2>/dev/null
+```
+
+Capture the stdout of `preprocess.mjs` — each line is a path to a filtered session file.
+
+### Step 2: Extract sizing metrics
+
+Use quick one-liners to extract counts — do NOT read the full JSON files into the main context:
+
+```bash
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/deprecated-scan.json '.dependencies | length'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/deprecated-scan.json '.explicit_markers | length'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/exports-scan.json '.stats.total_exports'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/exports-scan.json '.stats.total_files'
+```
+
+The session count is the number of lines from `preprocess.mjs` stdout.
+
+**Time estimate formulas:**
+
+| Phase                    | Formula                                 | Example                 |
+| ------------------------ | --------------------------------------- | ----------------------- |
+| Holistic source analysis | `3 + (total_exports / 500)` min, cap 12 | 3,470 exports → ~10 min |
+| Session log mining       | `1 + (sessions × 0.25)` min, cap 12     | 25 sessions → ~7 min    |
+
+### Step 3: Present the menu
+
+Use `AskUserQuestion` with `multiSelect: true`. Include actual numbers from Step 2:
+
+> **Which additional analysis phases would you like to run?**
+>
+> 📦 **Holistic Source Analysis** — {exports} exports across {files} files, {deps} dependencies, {markers} deprecation markers. Estimated: ~{N} min
+>
+> 💬 **Session Log Mining** — {sessions} qualifying sessions found. Estimated: ~{N} min
+
+Options (as `multiSelect: true`):
+
+- **Holistic Source Analysis (~N min)** — "Deep-read exports to find misleading APIs and deprecated patterns"
+- **Session Log Mining (~N min)** — "Mine Claude session history for confusion signals"
+- **Skip both** — "Proceed with git archaeology results only"
+
+Omit any option where the data count is zero (e.g., if no sessions qualify, don't show the session mining option). If both counts are zero, skip the menu entirely and proceed to Phase 4.
+
+### Step 4: Execute selected phases
+
+Based on the user's selection:
+
+- **Holistic Source Analysis selected:** Jump to the "Holistic Source Analysis" section below, starting at **Step 2** (scripts already ran in Step 1 above).
+- **Session Log Mining selected:** Jump to the "Session Log Mining" section below, starting at **Step 2** (preprocessing already ran in Step 1 above). Use the session file paths captured in Step 1.
+- **Both selected:** Run both, starting each at Step 2.
+- **Skip both:** Proceed directly to Phase 4.
+
+### Step 5: Cleanup
+
+Regardless of what the user selected, clean up temporary files before proceeding to Phase 4:
+
+```bash
+rm -rf /tmp/codeyam-memory/ /tmp/cc-session-analysis/
+```
+
+---
+
+## Additional Analysis Phase: Holistic Source Analysis
+
+Holistic analysis reads the codebase cross-cuttingly to find **latent confusion** — problems
+that haven't caused bugs yet but will mislead a future agent reading code locally.
+
+### Prerequisites
+
+- Project must contain `.ts`, `.tsx`, `.js`, or `.jsx` source files
+- If no source files are found, skip this phase entirely
+
+### Step 1: Run extraction scripts
+
+Handled by Phase 3B. Proceed to Step 2.
+
+### Step 2: Launch analysis subagents (concurrent)
+
+Read the prompt templates and launch both as Task agents concurrently. **Do NOT read the
+scan data into the main context** — it can be hundreds of KB. Each subagent reads its own
+data file via the Read tool.
+
+1. **Deprecated Pattern agent** — Read `.claude/skills/codeyam-memory/scripts/holistic-analysis/deprecated-prompt.md` for the
+   prompt template. Launch as a foreground Task agent (model: sonnet) with the prompt template
+   content. The agent reads `/tmp/codeyam-memory/deprecated-scan.json` itself, uses Grep to
+   find remaining callsites, and returns its findings JSON in the response.
+
+2. **Misleading API agent** — Read `.claude/skills/codeyam-memory/scripts/holistic-analysis/misleading-api-prompt.md` for the
+   prompt template. Launch as a foreground Task agent (model: sonnet) with the prompt template
+   content. The agent reads `/tmp/codeyam-memory/exports-scan.json` itself, uses Read to
+   inspect suspicious functions, and returns its findings JSON in the response.
+
+Both agents return their findings JSON and a brief summary directly in their response.
+
+**Context budget note:** The exports index alone can be 400KB+. Never read it into the main
+context. Subagents run as foreground Task agents and have full filesystem access including
+`/tmp/`.
+
+### Step 3: Integrate findings
+
+Parse the findings JSON from each subagent's response. For each finding:
+
+- **Deprecated patterns** get confusion score **4** (comparable to "workaround/hack" signal).
+  If an explicit `@deprecated` marker exists, bump to **5**.
+- **Misleading APIs** get confusion score **4** for medium severity, **6** for high severity
+  (where "high" means the mismatch could cause data corruption or silent failures).
+
+Add findings to the evidence pool alongside git archaeology results. They flow into
+Phase 4 (evidence-based user questions) and Phase 5 (rule generation) normally.
+
+### Step 4: Cleanup
+
+Handled by Phase 3B Step 5.
+
+---
+
+## Additional Analysis Phase: Session Log Mining
+
+This phase mines Claude Code session transcripts for empirical confusion: user corrections, wrong assumptions, re-edits, tribal knowledge gaps. It complements the git archaeology in Phase 2 with direct evidence from actual Claude sessions.
+
+### Step 1: Preprocess Sessions
+
+Handled by Phase 3B. Use the session file paths captured there.
+
+### Step 2: Launch Haiku Subagents
+
+Read the prompt template from `.claude/skills/codeyam-memory/scripts/session-mining/analyze-prompt.md`.
+
+For each filtered session file from Step 1:
+
+- If the file is **<200KB**: launch one Haiku Task agent
+- If the file is **>200KB**: chunk into ~200KB segments, launch one agent per chunk
+
+**Do NOT read session files into the main context** — they can be 20-40KB each and will
+exhaust the context window. Each subagent reads its own file via the Read tool. Each agent
+receives:
+
+1. The prompt template content
+2. The `/tmp/` file path to read (the agent reads it itself)
+3. Instruction to return a JSON array
+
+Launch agents in batches of **10** using the Task tool with `model: "haiku"`. **Use unique descriptions** for each agent (e.g., "Session mining batch 1 - session 1", "Session mining batch 1 - session 2", etc.; increment the batch number for each batch of 10). Wait for each batch to complete before launching the next. This keeps machine load manageable — a poweruser may have 30+ sessions qualifying.
+
+### Step 3: Collect and Validate Findings
+
+Parse each agent's response as JSON. Validate:
+
+- Must be an array
+- Each element must have `signal` and `summary` fields
+- `signal` must be one of: `USER_CORRECTION`, `RE_EDIT`, `FAILED_PIVOT`, `WRONG_ASSUMPTION`, `TRIBAL_KNOWLEDGE`, `APPROACH_PIVOT`
+
+If >50% of agents return invalid output, warn the user before continuing. Otherwise, silently skip invalid results.
+
+**Filter out environment-specific findings.** Discard any finding that relates to the developer's local machine setup rather than the project's codebase — e.g., bare repo checkout layouts, local tool versions, IDE configuration, shell aliases, filesystem paths, or permission issues. The rules we generate must be useful to _any_ developer cloning the repo, not just the one whose sessions we mined.
+
+### Step 4: Deduplicate Across Sessions
+
+Three-pass merge:
+
+1. **Cluster by `topic`** — group all findings with the same topic label
+2. **Rank within each cluster** — priority order: `USER_CORRECTION` > `TRIBAL_KNOWLEDGE` > `WRONG_ASSUMPTION` > `FAILED_PIVOT` > `RE_EDIT` > `APPROACH_PIVOT`
+3. **Count session occurrences** — add `session_count` to each merged finding
+
+Output: one merged finding per topic, with `session_count`, strongest signal type, and collected file paths.
+
+### Step 5: Feed into Phase 3 Scoring
+
+Additional scoring weights for session-mining signals:
+
+| Signal                              | Weight   |
+| ----------------------------------- | -------- |
+| User correction (session)           | 7        |
+| Tribal knowledge provided (session) | 6        |
+| Wrong assumption caught (session)   | 5        |
+| Re-edit of same file (session)      | 4        |
+| Failed-then-pivoted (session)       | 3        |
+| Appearing in 3+ sessions            | +3 bonus |
+
+These merge into the Phase 3 scoring table above. Session-mined findings then flow into Phase 4 (evidence-based questions) and Phase 5 (rule generation) alongside git archaeology findings.
+
+### Step 6: Cleanup
+
+Handled by Phase 3B Step 5.
+
 ---
 
 ## Phase 4: Ask Evidence-Based Questions
@@ -282,6 +491,12 @@ Before generating each rule, verify it passes these tests:
 - If YES → definitely document it
 - If NO → reconsider its value
 
+**For holistic analysis findings**, the validation checks apply with these adjustments:
+
+- **Evidence check:** Satisfied by structural evidence from source analysis (e.g., "name implies pure computation but implementation writes to cache on line 47") rather than git commit history.
+- **Code-derivable check:** These findings ARE derived from code — but from a cross-cutting read that a local reader wouldn't perform. The rule is valuable if it captures insight that requires reading multiple files or tracing non-obvious call chains.
+- **Prevention check:** "Would this rule prevent a future agent from being misled?" rather than "would it have prevented a past commit?"
+
 ### Rule Quality Examples
 
 **✅ Good rule** (passes all tests):

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