causal_trace:
your AI already knows why this broke

Watch how a stateless AI assistant handles a recurring error. The build fails with "cannot find module'ioredis'" after a dependency change.

The AI reasons it out from first principles: checks package.json, suggests reinstalling, proposes three fixes, lands on the right one after a few minutes. Perfectly competent work.

Two weeks later, same error, different branch. The AI does the exact same dance — because to it, this is the first time.

The knowledge from last time evaporated at the end of that session. You pay the full debugging cost again. And again.

The reason this stays invisible is that each individual instance looks reasonable. Ten minutes is not an outrage. Nobody files a ticket about ten minutes.

It only becomes visible when you multiply: one recurring bug class, four engineers, a handful of encounters each over a quarter. The time is real, it is spent, and no artefact anywhere records that it was spent on something already solved.

causal_trace is the first thing cachly runs when an error shows up — before any file is read or grepped. It takes the symptom and asks the Brain a single question: have we caused and fixed this before?

causal_trace(
  problem: "build fails: cannot find module 'ioredis'"
)

// → Brain hit (confidence 0.94):
//   ROOT CAUSE: ioredis is a peerDependency, not installed by
//     'npm ci --ignore-scripts' in the publish workflow
//   FIX: add 'npm install ioredis' before build, or move it to
//     dependencies
//   First seen: 2026-05-12 · confirmed 4× · last 2026-06-01

If the Brain has the answer, your AI applies the known fix directly and skips the rediscovery entirely.

If it doesn't, the AI debugs normally — and learns the lesson so the next occurrence is instant.

Plain search over past errors returns lookalikes — anything with "module not found" in it. That's noisy and often wrong.

causal_trace is built around cause and effect: it stores what actually triggered a failure and what actually resolved it, linked together.

So when a similar symptom returns, you don't get "here are five vaguely related errors." You get "this specific symptom was caused by X and fixed by Y, with confidence Z, confirmed N times." That's the difference between a search index and a Brain.

The evidence line matters more than it looks. A result you cannot argue with is a result you have to either accept or ignore wholesale.

A result carrying its own confirmation count can be weighed. Four confirmations across three months is a different proposition from one confirmation last Tuesday, and a person deciding whether to apply a fix at 6pm on a Friday should be able to see which one they have.

One practical note, because it decides whether any of this works: pass the actual symptom, not your theory about it.

“build fails: cannot find module 'ioredis'” is a symptom. “dependency resolution is broken” is a diagnosis, and usually a wrong one — it is the thing you were about to spend ten minutes disproving.

The Brain matches on what was observed, because that is what was recorded last time. Paste the error. Keep the module name, the exit code, the failing command. Strip the parts that are specific to this run, like absolute paths and timestamps, and leave everything that would look the same on someone else's machine.

Every traced fix carries a confidence score that moves with reality. A fix that's worked four times in a row sits near 0.95.

One that stopped working — because the underlying cause changed — erodes as soon as a new outcome contradicts it. cachly's CI integration even confirms fixes automatically: when a previously-failing build goes green after applying a known fix, that lesson's confidence ticks up without anyone touching it.

Automatic confirmation matters because manual confirmation does not happen. Nobody returns to a knowledge base after a green build to record that the advice held. The work is done, the branch is merged, the moment has passed.

A score that depends on people remembering to update it drifts toward whatever was true when someone last cared. Wiring it to an event that already occurs — a build going green — is the only version that survives contact with a busy week.

Worth stating plainly, because a confident wrong answer costs more than no answer at all.

A trace hit tells you this symptom was caused by X somewhere, sometime. It does not tell you that your situation is that situation. The stored fix came with conditions attached, and the conditions are the part most likely to have gone unrecorded.

Two habits keep this cheap. Read the confirmation count before the confidence score — a single confirmation is a lead, not an answer. And when the fix does not work, record that outcome instead of moving on, because a contradiction is exactly what stops the next person from walking into the same wall.

The first time you hit a bug, causal_trace costs you nothing — the Brain is empty for that symptom, your AI debugs as usual.

The compounding value shows up the second, fifth, twentieth time. The class of bugs that used to eat ten minutes each now resolves in seconds, across your whole team, in whatever tool you happen to be using that day.

That last clause is the one people underrate. The lesson is not stored in an editor, a chat history, or one person's head. Move to a different assistant next month and the same answer is there.

That's the whole thesis of cachly in one feature: knowledge your team already paid for, captured once and reused forever, instead of re-derived on every blank-slate session.

It is tempting to describe this as a speed feature. Faster debugging, fewer minutes lost. That framing undersells it slightly.

The minutes are real, but the more useful effect is that a solved problem stops being solvable-again. A bug class that has a recorded cause and a confirmed fix has left the category of things your team can lose time to twice.

The bugs that survive that treatment are the ones worth your attention — genuinely new, genuinely unclear, actually interesting.

Which is the quiet argument for recording lessons even when the fix felt trivial at the time. Triviality is not a property of the bug. It is a property of the person who has just spent ten minutes understanding it, and it does not transfer.