Memtrace Style Fingerprint

---
name: memtrace-style-fingerprint
description: "Always use before writing or editing source code in an indexed repo when choosing between competing idioms (ternary vs if-else, arrow vs function declaration, const vs let, await vs .then, early-return vs nested-return). Pull the codebase's empirical style norm from Memtrace and match it instead of re-deriving style from training priors. Do not maintain a markdown style guide for the project; the fingerprint is sampled live from the actual code."
---

## Overview

Every indexed Memtrace repository carries an empirical **style fingerprint** — descriptive histograms of competing AST idioms (ternary vs if-else, arrow vs function declaration, const vs let, await vs `.then`, early-return vs nested-return depth) computed at parse time and rolled up to Repository + Community level. This workflow tells you when and how to consult it so your edits match the codebase's existing idioms instead of drifting on stylistic choices the linter doesn't catch.

The fingerprint is **descriptive, not prescriptive**. It reports what the codebase actually does, not what a style guide says it should do. If the codebase deviates from a popular convention for some reason, the fingerprint captures the deviation and you should match the deviation — that's the whole point. For prescriptive bug/security/perf rules, use `find_code_review_issues` instead.

## When to use this workflow

| Situation | Action |
|---|---|
| About to write new code (function, component, module) in an indexed repo | Step 1 + Step 2 with `file_path=<the file you'll create>` |
| About to edit an existing file | Step 1 + Step 2 with `file_path=<that file>` |
| Asked "what's the convention here for X?" | Step 1 only — repo-mode fingerprint answers it |
| Deciding between two equivalent idioms (ternary vs if, arrow vs fn-decl, await vs then) | Step 2 with `file_path` — `delta_from_codebase_norm` tells you which idiom matches the norm |
| Reviewing a diff | Step 2 on each modified file — flag any new idioms that diverge from the file's language norm |
| Session start in a multi-day project | Read the `style:` line in `get_codebase_briefing` (auto-included) |

If the repo is not indexed in Memtrace, this workflow does not apply — fall back to your default behavior.

## Steps

### 1. Get the codebase's overall norm

Call `get_style_fingerprint(repo_id)` with no `file_path`. The response includes:

- `histogram` — raw counts (e.g. `ternary_count: 1005, if_stmt_count: 8087`)
- `ratios` — computed shares for each competing pair (e.g. `ternary_share: 0.11`)
- `dominant_idioms` — top-3 dimensions sorted by `|ratio - 0.5|` (strongest preferences first), each with a `dimension`, `ratio`, and human-readable `interpretation`
- `function_count` — sample size at the repo level
- `sample_threshold` — minimum observations before a ratio is committed (currently 20)

A `ratio` of `null` means the codebase doesn't have enough observations for that dimension to commit a norm — treat it as "no signal", do not assume one.

### 2. Get the file's deviation from the norm (when about to edit a specific file)

Call `get_style_fingerprint(repo_id, file_path=<file>)`. The response adds:

- `file_fingerprint` — the same shape as `histogram`/`ratios`/`function_count` but computed over just the functions in that file
- `codebase_fingerprint` — repo aggregate for comparison
- `delta_from_codebase_norm` — array of dimensions where the file diverges ≥0.15 from the codebase, sorted by absolute delta, capped at top 5. Each entry has `dimension`, `file_ratio`, `codebase_ratio`, `abs_delta`, and a `note` describing the direction

**Match the file's `language_fingerprint` (or `codebase_fingerprint` if per-language slicing isn't shipped yet), not the repo aggregate.** Per-language slicing prevents cross-applying Python norms to JS code or vice versa. Read the language-specific slice when present.

If `delta_from_codebase_norm` is empty, the file is already aligned — proceed without style adjustments. If it has entries, your edits should not amplify the divergence (e.g. don't add more ternaries to a file that's already above the codebase's ternary norm).

### 3. Read the briefing line at session start (passive)

`get_codebase_briefing(repo_id)` auto-includes a `style:` line in its summary when the sample threshold is met and at least one ratio is outside the 0.4..0.6 no-preference band. Format:

```
style: <interpretation 1> (<%>); <interpretation 2> (<%>); <interpretation 3> (<%>)
```

Example on a TS/JS-heavy codebase:

```
style: strongly prefers arrow functions (98%); strongly prefers async/await over .then chains (88%); strongly prefers const over let (94%)
```

You should already be reading the briefing at session start (per `memtrace-codebase-exploration`). The `style:` line lands in your context for free — no extra call needed.

## Decision points

| Condition | Action |
|---|---|
| `dominant_idioms[0].ratio >= 0.85` or `<= 0.15` | Treat as a hard preference — match it unless there's a specific structural reason not to |
| `dominant_idioms[0].ratio` in `0.65..0.85` or `0.15..0.35` | Treat as a soft preference — match it for new code, leave existing patterns alone |
| `ratio` in `0.4..0.6` | No clear preference — use your own judgment, match local file context |
| `ratio` is `null` (below sample threshold) | No signal — don't assume a norm; pick the idiom that fits the immediate context |
| `delta_from_codebase_norm` shows your target file already diverges from the norm | Don't amplify the divergence with your edits — match the codebase, not the outlier file |
| `file_fingerprint` is empty (file has no functions yet, or is a config file) | Use the language slice or repo aggregate; this is creation territory |

## Anti-patterns — do not do these

- **Reading the repo aggregate when editing a single-language file.** If the codebase is 70% TS / 30% Python, the repo aggregate mixes both. The `language_fingerprint` (when available) or `codebase_fingerprint.ratios` filtered by the file's language is what you should match. Cross-applying TS norms to a Python file is the failure mode this whole tool exists to prevent.
- **Treating the fingerprint as prescriptive.** It tells you what the codebase does. If the codebase consistently does something unusual, match that — don't override with "this isn't best practice" arguments. The whole point is to stop drifting from the codebase's own choices.
- **Calling `get_style_fingerprint` for every line of code.** Once per file at the start of an edit session is enough. The norm doesn't change between your edits within the same session.
- **Ignoring the briefing line.** It auto-loads into your context. If you act on style choices in an edit session without reading it first, you're spending tool calls to re-derive something you already had.
- **Adding a markdown style guide to the project.** The fingerprint is the style guide. It refreshes on every reindex. A markdown file would either duplicate it or contradict it.

## What this workflow does NOT cover

- **Security / bug / performance rules** — use `find_code_review_issues` (prescriptive deterministic review).
- **Naming case conventions** (camelCase vs snake_case vs PascalCase) — R2 candidate, not yet shipped. Until then, infer from the language and from nearby identifiers in the file you're editing.
- **Comment / docstring style** — not in scope; use file-local examples.
- **Architecture / module-organization decisions** — see `memtrace-codebase-exploration` and `memtrace-refactoring-guide`.

## Why this exists

Without this workflow, LLM editors drift session-to-session on style choices that aren't enforced by linters — one session uses ternaries, the next doesn't; one uses arrow functions, the next uses `function`. The fix isn't a manually-maintained style guide (stale by week 2). The fix is sampling the codebase's actual idioms at parse time and reading them before each edit. The fingerprint is computed in the same parse pass as cyclomatic + cognitive complexity at sub-1% overhead, so the cost of providing the answer is near zero.