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.

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 weekly picture.** Failures group by week, file, tool and code. 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 small negative signal. Permission, token-limit and rate-limit failures weigh more than an ordinary miss, because those tend to mean the guidance sent the assistant somewhere it could not go. The signal joins the loop described in [what makes knowledge rank higher](/docs/retrieval/how-retrieval-works). Knowledge that keeps showing up in turns that go badly gradually stops being 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 never does

It never blocks a tool call, never slows one down, and never appears 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.