Consult Scar before any consequential act — not just before searching the codebase

The rule

Before investigating a bug, answering an architecture question, starting an implementation, or doing anything whose consequence lands outside this session — advancing a tracker item's status, sending a report, publishing something, pasting session content into a shared surface — ask Scar what it already knows. Call scar_recall with a plain sentence naming what this work could get wrong — the risk, failure or symptom, not the artifact you are about to produce. A query shaped like the deliverable ("writing a bug-tracker entry", "updating the codebase map") retrieves topical neighbours; a query shaped like the risk retrieves the trap. Only skip it once Scar has nothing left to answer.

Scar is consulted through retrieval, never by reading. Do not grep, list, or open raw entry files to answer a question — that layer is ~2.2M tokens and exists as an audit trail, reachable only by drilling from a recalled lesson with scar_evidence to verify one specific claim.

The scar

Incident 1. Grepping a large unfamiliar codebase blind is the most expensive possible first move, and it's the default instinct. In a codebase where a single screen file ran to several thousand lines, answering "where does this behavior come from?" from source took a full session. The same question had a two-paragraph answer in an existing concept entry written weeks earlier.

Incident 2 — the reason this rule now names a tool instead of a grep. This rule originally said to grep -r "type: bug" over the entry folder. That instruction worked at a hundred entries and quietly stopped working at a thousand: the archive reached ~1,200 entries and ~2.2M tokens, so no agent could hold what a grep returned, and the archive became write-only — comprehensive, searchable in principle, never actually read. The same classes of bug kept recurring against a knowledge base that documented every one of them.

The failure was not that the rule was ignored. It was followed, and following it stopped helping, because the mechanism it named didn't scale with the corpus it pointed at. A rule that names a mechanism inherits that mechanism's limits — so when the retrieval layer changed, the rule had to change with it, or it would have kept sending agents at the one layer they must never load.

Incident 3. The rule's own title and wording said "before searching the codebase." A session advanced two tracker items to a status that claimed the work was pickup-able when it wasn't, and pasted private working-note phrasing verbatim into an org-visible tracker item — neither act involved reading or writing code, so the rule never fired, even though read-before-act was followed for actual code search that same session. The scope word ("codebase") did the same thing Incident 2's mechanism word did: it told the agent exactly what to skip checking. A rule that names its trigger narrowly gets applied narrowly, no matter how broad its intent.

Incident 4 — the same narrowing, applied to what counts as readable. Reported 2026-08-25 as the second half of one usage report. A background job was not completing. Five consecutive passes theorised about it from the outside — payload shape, request size, field types — while the worker's own source sat unread in a checked-out sibling repository the whole time. The session that finally read it end to end spent about twenty minutes and produced a specific testable cause plus two theories eliminated by reading rather than guessing.

Nothing was skipped through carelessness: the rule was being followed, and Scar WAS consulted. The narrowing was in what "read" was taken to mean. A vendored dependency, a sibling checkout and a server's node_modules read as third-party — someone else's code, not ours, and therefore not something you open — when they are all first-party reading and are usually the cheapest source of truth in the tree. The rule already forbids modelling something you could simply read; it had never said that the thing you could read includes code you did not write.

The report also named the retrieval half, which is why this rule gained triggers. The principle existed, correctly stated, inside a lesson about polling a progress field — reachable only by someone already thinking about progress fields, and therefore silent for the five passes when it was worth the most. Both were fixed: the general form is here, in a rule, which outranks a lesson; the lesson keeps its own copy of the surface. The systemic version of that failure is career/lessons/2026-08-17-an-incident-log-indexed-by-surface-hides-any-cause-that-recurs-across-surfaces — a record filed under where a defect appeared hides every other route to the same cause.

How to apply

1. scar_recall with the task stated as a sentence — "debugging an auth session lost after a redirect", "advancing a tracker item to ready-for-QA before the branch is merged" — before any codebase search or any act whose consequence lands outside this session. Lessons declare the phrasing that should surface them, so a natural description outranks keywords.
2. Read the returned rules first and the lessons second. A rule is in force; a lesson is a claim with evidence behind it.
3. If it answers the question, use it — don't override documented findings without a specific reason, and if you do override, say why and report it with scar_learn (harm) so the ranking learns.
4. To check one claim you're about to rely on, scar_evidence on that lesson. That is the only legitimate route to raw entries, and it returns excerpts, not bodies.
5. If nothing matches, the codebase search is now justified — and its result becomes a new entry (see write-after-solve).
6. Say in one line what you recalled and how it changed the plan. An unstated consultation is indistinguishable from none (see enforce-dont-declare).

Changelog

• 2026-08-25 — Scar count 3 → 4, and the rule gained triggers (rules had been indexed with an empty trigger list, so the layer that outranks lessons had the narrowest indexed surface in the corpus). Scoped from "read Scar" to "read anything cheaper than a theory, including code you did not write". Incident 4.
• 2026-08-11 — Scar count 2 → 3. Retitled and rescoped from "before searching the codebase" to "before any consequential act" after a session that skipped the rule entirely for two non-code acts (a false tracker status, a pasted private note) because the wording only named code search. Mirrored into core/AGENTS.md step 2's examples, the file every adopting project actually loads.
• 2026-08-11 — Rewritten for the distillation pivot; scar count 1 → 2. The rule's intent is unchanged. Its mechanism moved from grepping entries to scar_recall over the distillate, because the entry layer became unloadable. Reading raw entries is now explicitly forbidden by the same rule that used to require it.