When an automated workflow fails, I want to know which recorded operation failed first, which later operations depended on it, and which evidence supports that connection. CipherClaw is an open-source engineering project for investigating recorded multi-agent runs. Its source gives a concrete way to examine how that investigation is assembled.[1]
This is a source-code walkthrough of repository revision efcb3f6463b0b600f28f015421b0fdd866e84536, inspected October 29, 2026. It is grouped into the January–March archive as a retrospective and was published October 29, 2026. I am not claiming that the current revision existed in March, that a customer ran it, or that this review executed the test suite.
Start with the input contract
The causal-graph module accepts a debug session and a trace. A trace contains spans: records of individual operations. The function builds a map of those spans, then creates graph nodes from their identifiers, agent identifiers, operation names, timestamps, duration, status, domain, and attributes.[2]
This means the analysis starts with supplied instrumentation. The toolkit does not discover an unrecorded database write by looking at the surrounding text. If a workflow fails to record a child operation or gives it an incorrect parent, the investigation will inherit that gap. I would make trace quality an acceptance requirement before using the resulting graph during an incident.
For a business workflow, that translates into practical questions. Is the retrieval operation recorded separately from the model response? Does the customer-record write have its own status? Can a reviewer tell whether an approval happened before the write? Those are integration questions that the application owner must answer while producing the traces.
How the graph is assembled
The inspected function creates one node per span identifier that is not already in the session graph. It then looks at parentSpanId. When it finds both the parent and child nodes, it adds the parent-child relationship and an edge between them. It avoids adding the same edge twice.[2]
The edge is labeled error_propagation when the child span has error or critical status; otherwise it is labeled control_flow. That classification is derived from recorded status and hierarchy. It should be read as the toolkit's representation of the trace, rather than independent proof of the physical cause of a failure.
After adding nodes and edges, the module calculates node depths, identifies candidate root causes, assigns scores, finds a critical path, and collects impacted nodes. Each step is visible in the source. That makes the project useful for a technical interview: a reviewer can move from a public claim to the function that implements it and ask about the assumptions.
What a root-cause score actually means
The candidate selection rule is specific. An error or critical node is treated as a root cause when all its recorded parents are non-error nodes. The score for such a candidate starts at 0.5 and increases according to the proportion of error nodes found among its descendants. Other error nodes receive a different, smaller formula based on their error parents.[2]
Although the field is named rootCauseProbability, the inspected code establishes a heuristic score. It does not establish a calibrated statistical probability measured against an incident dataset. I would explain that directly to an operator. A high score is a reason to inspect a candidate, not a reason to skip the underlying evidence.
Consider a hypothetical chain: a document lookup fails, the drafting step fails because the document is missing, and the delivery step fails because no draft exists. With accurate parent relationships and statuses, this kind of graph can help a reviewer work back through the recorded chain. That is an illustrative scenario, not a measured deployment outcome for CipherClaw.
A more difficult case is a dependency that fails silently while its span reports success. The status-based rule has less useful evidence in that situation. The remedy starts with better instrumentation and error semantics. Renaming a score cannot compensate for a successful status attached to a failed business action.
Reading the critical path carefully
The source describes its critical path as the longest path through error nodes. The implementation searches from candidate roots and follows children whose status is error or critical.[2] This is a failure-chain view. It is not, from this function, a duration-weighted performance critical path.
That distinction matters during a demo. A long chain of failures might explain propagation, while a single slow successful operation might explain latency. Those are different investigations. I would present the failure path with its actual definition and inspect duration separately when the question is performance.
The impacted-node collection walks descendants from each candidate root. This identifies nodes connected beneath those candidates in the recorded graph. It does not establish that every descendant produced a customer-visible incident. A reviewer still needs to inspect the business effect and whether a recovery or fallback succeeded.
Breakpoints make inspection more targeted
The breakpoint module provides conditions for capturing a snapshot during span processing. The inspected code includes conditions for an error, a tool call, a particular agent, a memory operation, latency, cost, token usage, hierarchy events, and a conditional expression. It skips disabled breakpoints and breakpoints whose hit limit has been reached.[3]
The conditional branch delegates to evaluateCondition. The current README documents a bounded expression language and explicitly states that conditions cannot execute JavaScript. It also documents limits and unsupported syntax.[1] This review inspected the call site and the published contract; it did not independently audit the complete interpreter or execute adversarial inputs.
I would demonstrate a breakpoint with a synthetic trace before connecting sensitive production telemetry. The expected result should identify the triggering span and retain enough context to investigate. A second example should show the condition not matching. That keeps the demonstration tied to observable behavior rather than a screenshot of a configuration screen.
A bounded behavior check
For this review, I also ran a synthetic check against the inspected commit using Bun. The input contained three spans: a successful lookup, a failed draft operation beneath it, and a failed delivery beneath the draft. Seven assertions passed: the graph contained three nodes and two edges; the draft was the candidate root; its heuristic score was 0.75; the failure path contained draft then delivery; and ingesting the same trace again did not increase node or edge counts.
This is a repeatable check of the causal-graph module on constructed data. It does not establish behavior on production traces, complete engine integration, interpreter safety, or the full repository test suite. The test script and timestamped result are retained with the editorial evidence packet.
Evidence boundaries for this project
The public repository is inspectable evidence of the implementation. The specific graph and breakpoint functions described here were read directly. The README's test-count badge and broad capability descriptions are author-maintained claims, not fresh test results from this review.[1]
A previous internal review recorded a passing unit suite at an older revision. I would not transfer that receipt to the current revision. To make a current runtime claim, the next reviewer needs to run the documented commands against the exact commit and retain the output. To make a production claim, they need a separate deployment and representative workload receipt.
The review also does not establish reduced incident time, customer adoption, revenue, security certification, or a successful prediction of a future failure. Those claims require their own evidence. The value demonstrated here is narrower and inspectable: a concrete implementation turns supplied span records into a graph and applies documented rules to rank places to investigate.
What I would require before integrating it
I would first define the trace fields and identify the person responsible for their accuracy. I would then prepare synthetic examples for a successful chain, a failed parent with failed children, a missing parent, and a failure that recovers. The expected investigation output should be written down before running the examples.
Next, I would review the handling of sensitive attributes. Operational traces can contain client identifiers and document content. The application integrating the toolkit must decide what enters the trace, who may inspect it, and how long it remains available. This article makes no claim that the causal-graph function provides those controls.
Finally, I would compare the tool's output with an engineer's reading of the same trace. Disagreement is useful evidence: it can expose an instrumentation gap, an unsuitable heuristic, or an unclear business event. That comparison is how I would decide whether the integration helps a particular team.
Inspect CipherClaw's public repository and follow a finding back to the code that produced it.
Sources and editorial evidence
- [1]README at inspected revisiongithub.com/Alexi5000/CipherClaw/blob/efcb3f6463b0b600f28f015421b0fdd866e84536/README.md
- [2]Causal graph implementationgithub.com/Alexi5000/CipherClaw/blob/efcb3f6463b0b600f28f015421b0fdd866e84536/src/core/causal-graph.ts
- [3]Breakpoint implementationgithub.com/Alexi5000/CipherClaw/blob/efcb3f6463b0b600f28f015421b0fdd866e84536/src/core/breakpoints.ts