negative-result-scope

Negative Result Scope

A negative result is a claim about your search, not about the codebase. When you report absence:

State the scope inline — zero across <paths>, never a bare “does not exist” / “greenfield”.
“I can’t edit it” ≠ “it doesn’t count” — vendored, submodule and platform code is in scope for discovery; consult its indexes first.
Search wide — a false “already exists” self-corrects; a false “greenfield” is baked into plans and contracts.

A stated-but-unexecuted scope is worse than no scope. State only greps you actually ran, and prefer pasting the exact command over describing it — a pasted command is checkable, a described one is not. This failure is likeliest exactly when writing a summary of verification work, which is when the temptation to describe rather than re-run is highest.

Reviewing an absence claim, ask “what did you search?”, not “are you sure?”.

Mirror case — a reported IDENTIFIER is a claim about what you read. State a SHA, PR/issue number, line, version, path, or timestamp only after reading it back from the source (git log -1 --format=%H, gh pr view --json number) — a truncated/piped command’s output is not a read, and it fails silently. Read commit times under TZ=UTC (the repo-local default makes a copied +07:00 time with a Z suffix wrong by the offset, still well-formed); sanity-check against “has this happened yet?” — a window ending in the future is the cheapest tell. Incident: docs/negative-result-scope.md.

A SUMMARY handed to another agent is also a claim about what you read. When a brief asserts how code behaves (“the server ignores X”, “this dependency is absent”, “use migration N”), the receiver must verify it against the source before building on it, and the sender should mark which parts are observed versus recalled — a brief is written from memory of a read, not from the read itself, and fails silently because the receiver cannot tell a checked claim from a plausible one. An agent that finds the brief contradicts the source should follow the source and say so; that is the agent working correctly, not going off-spec.

Mirror case — a grep over a local clone is a claim about that checkout, not the project. A clone that is behind, or sitting on a feature branch, yields a confidently-scoped false absence: the scope statement is accurate and the conclusion is false, so “state your scope” does not catch it. When reporting absence in a repo you did not author this session, verify the checkout is current first — git fetch, then git rev-parse --abbrev-ref HEAD and git rev-list --count HEAD..origin/main — or grep the ref directly via git show origin/main:<path>. State the ref you searched, not just the path.

Full obligations, how to apply, example, anti-patterns, incident: docs/negative-result-scope.md.