Skip to content
Pathrule

docs

Files that slow an assistant down

How Pathrule records where an AI assistant fails while working, what it does with those failures, and what the signal cannot see.

On this page

Some files are harder for an assistant to work in than others, and the reason is usually not the code itself. A path in your docs that moved. A generated file that cannot be edited safely. A directory that needs a permission the agent does not have. You already know which files those are, roughly, from having been annoyed by them. Pathrule records it precisely.

What gets recorded

When a tool an assistant calls fails, three things are stored: the kind of tool, the file it was working on, and a short code for how it failed. file_not_found, permission_denied, timeout, rate_limit, token_limit, syntax_error, or unknown when the failure is real but nothing recognises it.

That is the whole record. Not the command. Not the error message. Not the file. A count and a code, attached to a path. On a Cloud workspace these counts and codes are stored with the workspace in Pathrule Cloud.

The failure is observed, not reported. Pathrule's tool hook watches the call itself, so the count does not depend on the assistant noticing its own mistake, remembering a session, or calling anything afterwards. An assistant that fails quietly and moves on is recorded exactly like one that announces it. How long the call took is part of the same observation, which is what lets a command that hung be told apart from one that refused. This applies to clients where Pathrule has tool hooks: Claude Code and Codex. Cursor, GitHub Copilot and Windsurf have no Pathrule hooks, so their tool calls are not observed this way.

The path is normalised to workspace-relative form first, which matters more than it sounds. An absolute path on a laptop is /Users/<name>/…, and that name has no business travelling to shared knowledge. Relative paths also mean the same file groups correctly across a team, instead of once per machine.

What it is used for

A picture of where work gets stuck. Failures group by file, tool and code over time. What comes out is a short list rather than a chart: the files an assistant fails in most, and how. A file that keeps appearing under file_not_found is usually a stale path somewhere in your own instructions. One under syntax_error is usually a file that is genuinely awkward to edit. One under permission_denied is usually a setup problem you can fix once.

Retrieval learning. If a turn received knowledge from Pathrule and still ran into failures, that knowledge takes a negative signal, and some kinds of failure count for more than an ordinary miss because they tend to mean the guidance sent the assistant somewhere it could not go. The signal joins the loop described in how retrieval finds the right knowledge. Knowledge that keeps showing up in turns that go badly gradually becomes less likely to be chosen, without anyone having to review it.

What the signal cannot see

This part depends on which assistant you use, and it is not uniform.

File tools report failures properly. A read, edit or write that fails arrives with its message, gets classified, and lands on the right file. That is the case that matters, because a file path is what makes a count actionable.

Shell commands often do not. Some assistants report no exit code at all, so a command that fails and one that succeeds arrive looking identical. Pathrule does not infer a failure from output text: a search result can legitimately contain the words "no such file or directory", and a wrong failure attached to a file is worse than a missing one. When the assistant does not report a failure, nothing is recorded, and when it reports one that no rule recognises, the code is unknown rather than a guess.

What it does not do

Recording a failure does not block a tool call and does not appear in the assistant's context. A failure is a fact about your codebase, recorded after the fact. It does not change what the assistant is allowed to do, and a file with a bad record is not treated as off limits. Nothing here is a score attached to a person: the record is about files, not about who was working in them.