claim-scope

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->

# Claim Scope

**The defect this prevents:** an agent runs a correct check, then states a
conclusion the check could not support, with full confidence and no hedge. The
check is not wrong. The *reach* of the check is wrong, and nothing in the
sentence records the difference.

Observed 2026-09-04. An agent grepped `@vercel/blob` in a local checkout of
a private app repo, found nothing, and reported: *"there is no blob path; the audio
lives only in Postgres; switching source is not possible."* The grep was
accurate. The checkout sat on a branch whose last commit was a day old, while
`origin/main` carried a merged blob migration that was **already deployed to
production**. The agent had reported a property of one working tree as a
property of the running system. Existing lint passed it clean, because the
sentence named its instrument (`grep`) and the mechanism-claim rule accepts
`grep` as an observation.

**Naming your instrument is not enough. The instrument must be able to see the
thing you are claiming.**

---

## The four layers

Every claim about a software system lives at exactly one of these. Decide which
one BEFORE writing the sentence.

| Layer | The claim is about | Nothing below it can prove this |
|---|---|---|
| **L1 · working tree** | this branch, this directory, right now | — |
| **L2 · repository** | origin, every branch, every worktree | L1 sees one branch of many |
| **L3 · deployed** | what is built and shipped and serving | L2 sees intent, not what shipped |
| **L4 · live behavior** | what it does when a person touches it | L3 sees the artifact, not its behavior |

The layers are a ladder, not a menu. **A claim at layer N requires an instrument
that reaches layer N.** Reaching higher is free and always valid; reaching lower
is the defect.

## Instrument reach — the lookup

Do not reason about this. Look it up.

| Instrument | Reaches | Blind to |
|---|---|---|
| `grep`, `cat`, `sed`, Read, Glob, reading a file | **L1** | other branches, other worktrees, what shipped, what it does |
| `git log`, `git status`, `git diff` (no fetch) | **L1** | anything not yet fetched |
| `git fetch --all` + `git log HEAD..origin/<branch>` | **L2** | whether it built or shipped |
| `git worktree list`, `git branch -a`, `gh pr list` | **L2** | same |
| `vercel ls` / `vercel inspect`, `gh run list`, deploy sha, build log | **L3** | runtime behavior under a real request |
| `curl -D-`, a real HTTP request, a screenshot, `ibr scan`, an AX probe, a live DB query | **L4** | nothing — this is the ground |

Two instruments that look similar and are not: `git log` reports what you have
fetched; `git log HEAD..origin/main` after a fetch reports what exists. The
first is L1. The second is L2.

## Procedure

Run this whenever a claim is about to be stated, not only when you doubt it.
Doubt is the thing that fails first.

**1. Write the claim as a sentence.** Then read it back and answer: *which layer
is this a claim about?* If the sentence contains "is deployed", "is running",
"is broken", "does not exist anywhere", "nothing does X" — it is L3 or L4, no
matter what you looked at.

**2. Look up the reach of every instrument you actually ran.** Not the ones you
could have run. The ones in your transcript.

**3. Compare.** If `max(instrument reach) < claim layer`, you have two legal
moves and no third:
   - **Go get the higher-layer evidence.** Usually cheap: one `git fetch`, one
     `curl -D-`, one `vercel ls`.
   - **Rewrite the claim down to the layer you actually reached**, explicitly:
     *"no blob dependency in the working tree of `fix/embedding-failures` at
     `3fe5298`"*. This is honest and often still useful.

   Stating the higher-layer claim anyway is the defect. There is no "probably".

**4. Stamp the time.** An L4 observation is true at its timestamp and nowhere
else. Record when you looked, not when you are speaking.

**5. Re-run before repeating.** Before restating an earlier L3/L4 result later in
the same session, re-run it. In the 2026-09-04 incident a correct `curl` at
05:32Z was still being quoted at 07:47Z; the deploy that falsified it landed at
07:07Z, inside the same conversation.

## Verify right-to-left

Default direction: **start at L4 and walk left toward source.**

Left-to-right (read source → infer behavior → assert it) manufactures confident
wrong answers, because the source you are looking at may not be the source that
is running. You cannot detect that from inside the source.

Right-to-left (observe behavior → explain it from the artifact → trace to the
code that produced it) cannot make that error. The rightmost layer is the only
one that cannot be stale about itself.

Worked example, the same incident done correctly:

- **L4 first.** `curl -D- -H "Range: bytes=0-1023"` → `HTTP 200`,
  `accept-ranges: none`. *Seeking is broken right now.* True regardless of any
  repo state.
- **L3 next.** `vercel ls` → production deploy Ready at 00:07:16 PDT.
  `gh run list` → CI red on that commit. *The blob code shipped.*
- **L2 next.** `git fetch` + `HEAD..origin/main` → the merge exists. `git
  worktree list` → the CI fix is stranded on an unpushed branch.
- **L1 last.** Read the merged route. It 307-redirects when `episode.audioUrl`
  is set and falls back otherwise. Now the L4 observation is *explained*:
  today's row predates the deploy, so it has no blob URL.

Reading the route first would have produced "seeking works now," which is false.
The L4 observation is what made the L1 reading mean anything.

## The pause trigger

These words may not be written until step 1–3 has run:

From tyroneross/build-loop, Apache-2.0.

More from tyroneross/build-loop