verify-through-the-real-path git:20261024.3da343aA

Immutable. This exact content never changes and is served at /api/v1/blob/956778dc883e3a81.

---
name: verify-through-the-real-path
description: >
  Use before claiming something works, is done, is safe, or is fast — verify
  through the actual trigger, real data, and representative conditions, not a
  convenient stand-in. Triggers on "verify", "confirm it works", "is it done",
  "benchmark", "ETA for a long run", "is this edge case reachable", "test the
  hook", "smoke test", and before declaring a fix complete.
---

# Verify Through the Real Path, Not a Proxy

**Type:** Open-source — client-agnostic methodology, no project-specific detail.

**Created by akbarsha — https://github.com/iamakbarsha1**

Distilled from repeated cases where a check passed against a convenient
stand-in while the real thing was broken.

**Licence:** Released under CC BY 4.0 — share and adapt for any purpose with
credit. Full text: `LICENSE` at the repository root.

**Feedback & Support:** If a rule here proves wrong or needs sharpening,
open an issue on the repository or contact the author at the profile link
above. If the problem is the agent not following a rule below rather than
the rule itself, that's an execution failure — acknowledge and correct it.

## The core rule

A convenient stand-in is not the thing you claimed works. Verify through the
actual trigger, real data, and representative conditions — not a shortcut
that inherits your ambient context or hides the tail.

## When this fires

**Where:** The moment before you say "works", "done", "safe", or "fast" —
signing off a hook- or cron-driven feature, quoting an ETA, citing a
benchmark, calling an edge case unreachable, or probing an unfamiliar CLI.

**The case this came from.** A sync-triggered feature was checked by calling
its function directly, and the check passed. The real event hook runs from a
different working directory, so it never resolved the relative config path and
silently never fired. The direct call had inherited the operator's cwd; the
trigger never had it.

**Another shape it takes.** *(Illustrative: A nightly report is "verified" by
running the generator in a terminal where the operator's cloud credentials are
already exported. Under the scheduler there is no such session, so every
nightly run fails auth and writes a zero-row file nobody opens for a month.)*

## Checks

- **Real trigger, not a direct call.** A feature fired by a hook, cron, or
  detached/background process is only verified by exercising the ACTUAL
  trigger — invoke the real hook/script with a representative payload, from a
  representative working directory, with the real environment — and observe
  the end effect (the commit, the file, the side effect). A direct call to
  the underlying function is a unit test: it inherits your ambient
  cwd/env/resolved paths that the real trigger never has. *(A sync-triggered
  feature passed a direct-call check, but the real event hook that fires it
  ran from a different working directory, never found the relative config, and
  silently never fired.)*
- **Smoke test = throughput floor, not an ETA.** A smoke test proves the
  pipeline works and gives a throughput FLOOR — not a wall-clock estimate.
  For multi-hour jobs, wall time is governed by tail effects a short sample
  can't see (host sleep/power throttling, item-size variance, throttling
  windows). Re-measure the instantaneous completion rate over time; don't
  trust smoke-rate × N. *(A short smoke run extrapolated to a few hours; the
  real run took roughly three times as long.)*
- **Micro-benchmark = upper bound.** A speedup that removes a FIXED cost
  (process startup, connection, allocation) is only as large as that cost's
  share of total time. A trivial input inflates that share — benchmark on a
  REPRESENTATIVE workload, and if you cite a micro-benchmark, label it an
  upper bound. *(A startup-strip showed a ~3.5x speedup on trivial input but
  only ~25% on the real workload, where a variable cost the micro-benchmark
  omitted dominates.)*
- **"Unreachable / safe / cosmetic" is only as strong as its invariant.**
  Name the invariant the verdict rests on, then check whether it is enforced
  LOCALLY (a guard in code you own) or merely assumed of an upstream. If
  merely assumed, verify it against live data and state it as an EMPIRICAL
  ceiling, not a structural one — and note the one-line local guard that
  would make it structural. *(A divert guard called "effectively unreachable"
  actually self-disabled when an upstream field was null; it was safe only
  because that upstream always populated the field — confirmed against tens
  of thousands of live rows, zero nulls — which is empirical, not
  guaranteed.)*
- **Call the resolver; don't ask the component.** Before designing any check,
  ask whether the system exposes the decision point itself — a resolver
  function, a dry-run, a plan output, an explain mode, a config dump. If it
  does, call it and read the value it computes. Asking a component to describe
  itself is self-report: it is bounded by what the component can see and cannot
  tell a correctly-applied setting from a coincidentally-matching one. Fall
  back to self-report only when no such surface exists, and label the result as
  self-report when you quote it. Then close the loop — confirm the resolver you
  called is the one the real path uses, not a parallel reimplementation beside
  it. *(Three of four checks on a model-routing config dispatched an agent and
  asked it to report its own model. The fourth found the resolver the
  dispatcher actually calls, ran it against the real config, and read the value
  that would have been passed: the same question, a categorically stronger
  answer, no more expensive — and the resolver had been available the whole
  time.)*
- **`--help` can execute.** Before running an unfamiliar CLI subcommand "just
  to see the flags", confirm the arg parser's unknown-flag behaviour first
  (read the dispatch code or grep for `--help`/usage). A parser that ignores
  unknown flags runs the subcommand with defaults — on a mutating/
  side-effecting subcommand, `--help` triggers a real execution. Prefer a
  guaranteed-safe probe: `--version`, a confirmed dry-run, or reading source.
  *(A `--help` probe on an unfamiliar mutating subcommand executed a real run
  — live side effects on dozens of records — before printing anything.)*

## Pre-flight check — before you claim it works

Re-read the checks above against what actually happened, not what you
intended:

- [ ] The claim was verified through the real trigger/path, not a convenient
      direct call that inherits favorable ambient context.
- [ ] Any timing claim from a smoke test is labeled a floor, and the live
      rate was checked on a representative run.
- [ ] Any benchmark cited is on a representative workload, or labeled an
      upper bound.
- [ ] Any "safe/unreachable/cosmetic" verdict names its invariant and states
      whether that invariant is locally enforced or only empirically true.
- [ ] You checked whether the system exposes its own resolver, dry-run, or
      explain mode and called it, rather than asking a component to report on
      itself — and any self-report quoted is labeled as such.
- [ ] Any unfamiliar CLI probed for its flags used a guaranteed-safe route
      (`--version`, a confirmed dry-run, or reading source), never `--help` on a
      mutating subcommand whose arg parser might execute it.

If any box is unchecked, the claim is not verified — go back and check it.