CLAUDE.md git:20260907.eda8098A

Immutable. This exact content never changes and is served at /api/v1/blob/95b3d86d666144f8.

# Project Rules

House rules a capable model wouldn't reach on its own. No restating of
ordinary good practice, and no architecture — that lives in
`docs/STATUS.md`, which gets reviewed. Rules naming modules rot silently;
behavioural rules don't. For trivial tasks, use judgment.

## Stance

Be concise, direct, and candid. Challenge weak assumptions. Keep verified
facts distinct from inference and from guesses, and say which you are
offering — "I checked and it says Y" and "it probably does Y" must not
read alike.

Ask only when a decision is materially ambiguous, risky, or needs
approval; otherwise choose, say so, continue. Exception: when a request
has several real readings that lead to different work, present them
instead of silently picking one.

## No keyword matching

Never use keyword or string matching for classification, routing,
affordance detection, or intent understanding — use an LLM call with a
natural-language description, embedding similarity, or another
meaning-based method. Keyword lists always miss edge cases. Only with
explicit permission.

## Write for the reader, not for yourself

Scratch files and working notes can use any shorthand. Everything else —
documents, prompts, code comments, commit messages, anything another person or
model will read — is addressed to an *other*. Use plain language, as short as
it can be without becoming ambiguous, in the register of a well-drafted
procedure.

**The test: if the reader has to reconstruct what you meant, the sentence
failed.** Three ways that happens, all found in this repo:

- **A metaphor standing in for a rule.** "Load-bearing" meant *mandatory*; say
  mandatory.
- **A term defined precisely, then reused loosely.** `delta` was a verdict, a
  form field, and a synonym for findings — in one document, within twenty
  lines.
- **Compression that reads as precision.** "One assertion" sounds exact and has
  no fixed size. Two models read it at different scales and neither misread it.

This is not a style preference. An instruction another model executes is a
specification, and a specification that can be read two ways will be.

Going forward, not backward: applies to new and edited text. Do not sweep the
repo for it, and leave argumentative prose written for a human reader alone.

## No mannered prose

Mannered prose substitutes metaphor and flourish for direct statement. Instead
of "a parameter worth varying," the mannered writer produces "a dial worth
turning." Instead of "this point still matters," they write "this point earns
its keep." The phrases exist to display the writer, not to convey the idea,
and readers can tell. That is why mannered prose irritates: it makes the
reader work harder so the writer can perform. It is also imprecise: metaphors
drag in connotations the writer did not choose and cannot control.

The fix is to say what you mean. When a literal phrase is available, use it.
This applies to everything written here: code comments, commit messages,
method documents, reports, essays, and replies in chat.

## Method documents are read whole

`METHOD.md`, `REVIEW.md`, `DELIVERY.md` — any document a workflow LLM reads as
its method — are edited only after reading the whole file in one piece. No
grep, no `sed -n`, no jumping to a line number, whether to compose a change or
to propose wording for one. Read it whole again before calling the edit done.

The non-obvious half: **grep finds strings, not ideas.** One requirement sat in
six places in six wordings; removing it from two left four, and the search
meant to catch them matched one. A fragment also hides register — a
justification clause, a term already defined two sections up, a second phrasing
of a rule that already exists.

No exception for a one-line change. Seven defects went into these three files
on 2026-08-31 and every one looked trivial while it was being made. The
workflow linter passed after all seven; it checks form, and says so.

## Sampling settings are code, not convention

`top_p` is 0.95 globally; temperature is per-model. Both live in
`src/chat/model_params.py` and resolve automatically — **never pass a
temperature literal to an LLM call**, and never treat a scenario default,
a `--help` string or a comment in a config file as evidence of what a run
will actually use.

Adding a model needs the publisher's recommended *agentic* temperature,
found by searching, plus explicit confirmation. If no recommendation
exists, say so and ask — don't pick. An unconfigured model raises rather
than inheriting, and that is the feature.

Twelve benchmark runs were discarded on 2026-08-24 because a documented
setting sat in a file the runner never read.

## Reuse over re-implementation

Before writing logic for a common task (fence stripping, JSON repair,
retry/backoff, path resolution, env reading), look for an existing
utility. If several sites need it and none exists, add one helper in
`utils/`. When a duplicate has crept in, consolidate rather than add a
third.

## KISS — and let the user carry a little

Review every plan for unnecessary complexity before proposing it. The
non-obvious half: prefer a significantly simpler design even when it
shifts a *minor* burden onto the user. The tell is machinery whose whole
purpose is to spare them one small explicit action — inference,
heuristics, disambiguation, and the guards those need. Name the trade
and let them choose; ask when unsure which way it falls.

Distinct from feature creep (that's about scope — do less). This is
about where the work sits when the feature is agreed.

## Surgical changes

Touch only what the request requires; match surrounding style even where
you'd choose differently. Clean up orphans *your* edit created; leave
pre-existing dead code alone and mention it instead. Nothing speculative —
no unasked features, no abstraction for one call site, no error handling
for impossible states.

## Verify against the real thing

Validate user-facing work in the real interface: run it, look at it,
screenshot it. Passing tests routinely coexist with a broken screen. When
you claim something works, say how you know — and if a check was skipped
or a test failed, say that plainly instead of reporting around it.