Engram Mistakes

engram-mistakes

Read this when about to modify code that has historical regret. The skill shells engramx mistakes and renders a bi-temporal block: what was believed at the time of the original change, when that belief was falsified, what the truth is now, and which pattern the lesson applies to.

It is the fastest way to stop your agent from repeating a mistake the repo has already burned to fix.

Layer 1 — Control Dials

Three parameters control every invocation. Override from user request or infer from context.

Override rules: mode → 1-3 when the file path is in node_modules, dist, build, .next, .nuxt, or coverage. Window → 5 when the user asks "lately" or "recent". Depth → 1 when the tool surface is a one-line edit and noise must stay low.

Layer 2 — Core Principles

1. Bi-temporal first. Every output must distinguish then-believed from truth-now. A flat single-line "X was a mistake" is the v3.x fallback — only used when the v9 fields are absent. Never invent the bi-temporal fields; if they're not in the graph, fall back legacy.
2. Pattern over instance. The applies-to field describes the kind of mistake (e.g. "useReducer + async + form-event handlers"). That's what trips the next agent, not the specific commit SHA. Lead with pattern in the heading.
3. Fail open, never silent. A missing engramx, corrupt graph.db, or unreachable mistake record never blocks an edit. Wrap every IO in try/catch; on failure emit zero output and let the operation proceed.
4. Proactive trumps reactive. A Mistake #1 warning that fires before Claude edits the file is worth ten warnings the user has to ask for. The PreToolUse hook does the proactive work. The CLI direct-invoke is the reactive surface for audits.
5. Truncate, don't bury. Surface the top depth entries. A 47-mistake list is noise — engram surfaces a "+42 more" indicator and trusts the user to ask for engramx mistakes --full if they want the dump.

Layer 3 — Decision Tree

What's the trigger?
├── User question matches /have i made this|any mistakes|past attempt|did i try/i
│   ├── File context detected from current message  → engramx mistakes -p . --source <file>
│   └── No file context                              → engramx mistakes -p . --since 30d
├── PreToolUse Edit / Write
│   ├── file_path matches /(ts|tsx|js|jsx|py|rb|go|rs|java|c|cpp|cs|php)$/
│   │   ├── path NOT in node_modules|dist|build       → fire engramx intercept (mistake-guard wraps)
│   │   └── path in excluded dir                      → stay silent
│   └── file_path is docs / config / lock file        → stay silent
├── PreToolUse Bash
│   ├── command contains a known dangerous pattern    → fire engramx intercept
│   └── otherwise                                      → stay silent
└── Manual /engram-mistakes invocation                 → engramx mistakes -p . --since 90d

Additional reads by need:

• Need the visual format spec? → references/output-format.md
• Need bi-temporal model background? → references/bi-temporal-model.md
• Need trigger pattern detail? → references/trigger-patterns.md
• Wondering why a mistake didn't fire? → references/anti-patterns.md (false-negative section)

Layer 4 — Invocation Variants

The same engramx data renders in three different surfaces. Pick by context.

The skill itself never picks the variant — it routes the user's intent to the correct engramx subcommand. The guard mode is configured separately via env var.

Layer 5 — Custom Invocations

For non-standard requests ("show me mistakes from last sprint only", "filter to authentication-related"), generate a MISTAKES.md spec first:

target:   <file glob or repo>
window:   <since date or duration>
filter:   <substring or regex on applies-to>
format:   structured | json | plain
limit:    <int>

Then map to engramx mistakes --since <window> --source <target> --format <format> --limit <limit>. The pack ships no new mistake-extraction logic — every query is a CLI invocation.

Layer 7 — Quality Gate

Before claiming the skill fired correctly, verify ALL of these.

If any check fails, the rendered output is not a rave-quality mistake surface — return to the underlying engramx invocation and verify the graph data shape before retry.

See also

• references/bi-temporal-model.md — why "then vs now" matters more than "what failed"
• references/output-format.md — exact byte-level format spec for the hook layout
• references/trigger-patterns.md — the auto-fire decision matrix expanded with examples
• references/anti-patterns.md — what makes a mistake surface noise instead of signal
• references/evaluation.md — measurable criteria for whether the skill is working in your repo

Privacy

engram-skill-pack ships zero egress. engramx (peer dependency) routes all graph data through local SQLite at ~/.engram/ and the per-project <project>/.engram/. No network calls happen during skill invocation. The pack is safe to install on a fully air-gapped workstation.

Cross-IDE

This pack targets Claude Code Skills. Same engramx data, different surfaces:

• Continue.dev → engramx-continue npm package
• VS Code / Cursor extension → nickcirv.engram-vscode on OpenVSX
• Other MCP clients → engramx-serve (HTTP) or direct CLI

All four wrappers read the same ~/.engram/graph.db. Install once, surface everywhere.