{
  "markdown": "# verifyfirst\n\n**A registry of software failures that report success.**\n\nLive at **[verifyfirst.dev](https://verifyfirst.dev)** · machine-readable at\n[`/registry.json`](https://verifyfirst.dev/registry.json) · CC0\n\n---\n\nA failure that crashes is cheap. It announces itself, and you fix it.\n\nA failure that *reports success* is expensive. The screenshot looks fine. The\ncommand exits zero. The endpoint returns 200. You move on, and the bug ships.\n\nThis is a reference for the moment before you claim work is done. It is\norganised by **the instrument you verified with** — not by the bug, because\nthe bug is the thing you are trying to find. You know how you looked. Look up\nwhat that method cannot see.\n\n```\n$ curl verifyfirst.dev/screenshot.txt\n\nVERIFYFIRST // screenshot\nA rendered image — You captured the page and looked at it.\n\nWHAT IT CANNOT SEE\n  - Time. A still frame cannot distinguish 'renders one frame then stops'\n    from 'renders one frame correctly'.\n  - Whether scripts ran at all, as opposed to running and producing this.\n  - Why an element is absent: never drawn, drawn transparent, drawn\n    offscreen, or covered.\n  ...\n```\n\n## Three ways in\n\n| You have | Door | Example |\n|---|---|---|\n| A task you just finished | [`/recipes`](https://verifyfirst.dev/recipes/) | \"I restarted the service\" → 5 checks before you call it done |\n| A symptom | [`/symptoms`](https://verifyfirst.dev/symptoms/) | \"the deploy ran but nothing changed\" → the failures that produce it |\n| A verification method | below | \"I took a screenshot\" → what it cannot see |\n\n## The six instruments\n\n| Instrument | You used it when | Plain text |\n|---|---|---|\n| `screenshot` | You captured the page and looked at it | [`/screenshot.txt`](https://verifyfirst.dev/screenshot.txt) |\n| `exit-code` | The command exited zero, so you moved on | [`/exit-code.txt`](https://verifyfirst.dev/exit-code.txt) |\n| `http-response` | You requested the URL and got 200 | [`/http-response.txt`](https://verifyfirst.dev/http-response.txt) |\n| `file-on-disk` | You read the config and it says the right thing | [`/file-on-disk.txt`](https://verifyfirst.dev/file-on-disk.txt) |\n| `process-list` | You checked `ps`, `pgrep`, or `systemctl status` | [`/process-list.txt`](https://verifyfirst.dev/process-list.txt) |\n| `log-output` | You read the output and it looked normal | [`/log-output.txt`](https://verifyfirst.dev/log-output.txt) |\n\n## Entry format\n\nEvery entry names the one observation that separates the two hypotheses:\n\n```json\n{\n  \"id\": \"NS-005\",\n  \"instrument\": \"exit-code\",\n  \"title\": \"enable --now does not restart an already-running unit\",\n  \"false_reading\": \"The command exits zero and the service is active. Conclusion drawn: the new code is live.\",\n  \"true_state\": \"systemctl enable --now starts a stopped unit. On a running one it is a no-op. The old process, with the old ExecStart, survives.\",\n  \"why_blind\": \"Exit code zero and `active (running)` are true statements about the wrong process.\",\n  \"discriminating_check\": \"systemctl show -p ExecStart NAME and ps -p $MAINPID -o args=\",\n  \"cost_of_missing\": \"A deploy is reported as complete twice while the previous binary keeps serving.\",\n  \"generalises_to\": \"Any idempotent-looking command whose semantics differ by current state.\"\n}\n```\n\nA check qualifies **only if it returns different output under the two\nhypotheses.** An observation that comes out the same either way has confirmed\nnothing, however much work it took to produce.\n\n## MCP server\n\nQuery the registry from your own tooling instead of fetching web pages:\n\n```bash\nclaude mcp add verifyfirst -- uvx verifyfirst-mcp\n```\n\nOn [PyPI](https://pypi.org/project/verifyfirst-mcp/) and in the\n[official MCP registry](https://registry.modelcontextprotocol.io/) as\n`io.github.simulacra/verifyfirst`.\n\nPython 3.12 stdlib only — no pip install, no dependencies, works offline from\nthe bundled registry copy. Tools: `list_instruments`, `get_instrument`,\n`blind_spots`, `search`, `get_entry`, `get_protocol`.\n\n`blind_spots` is the one to reach for mid-task. It takes loose names — `curl`,\n`200`, `pgrep`, `systemctl`, `stdout`, `playwright` all resolve — and returns\njust the list, terse enough to read before you commit to a verification.\n\nFull install options for other MCP clients: [`mcp/README.md`](mcp/README.md).\n\n## The protocol\n\nShort enough to paste into a system prompt:\n\n> Before reporting work complete: name the instrument you verified with, state\n> what that instrument cannot see, run one check whose result would differ if\n> the work had failed, and report the observation rather than the conclusion.\n> Prefer resolved values over authored ones.\n\n## What this cannot see\n\nIt is Unix- and web-heavy — of 74 cited sources, 19 are Linux man pages and 11\nare RFCs, and nothing comes from Windows, mobile, embedded, the JVM, or ML\npipelines. The checks were reproduced on one machine. Most entries were written\nin a single day.\n\nAnd the deepest limit, which cannot be fixed from inside: **an entry exists only\nbecause somebody eventually noticed.** Failures that are silent *and* have never\nbeen caught are, by construction, absent, and there is no way to estimate how\nmany there are. The registry's own instrument is \"somebody noticed\", and it is\nblind to exactly the thing it is about.\n\nFull statement: [verifyfirst.dev/limits](https://verifyfirst.dev/limits/). CI\nrequires it to exist.\n\n## The standard\n\n**Every entry is drawn from a failure that was actually observed and\ndiagnosed. None are hypothetical.**\n\nThat bar is the whole value of this. A registry of plausible-sounding bugs\nwould be indistinguishable from a registry of real ones — which is precisely\nthe failure mode catalogued here, so getting it wrong would build the bug into\nthe thing.\n\n## Contributing\n\nEntries need a **discriminating check** — one observation that returns a\ndifferent result depending on which hypothesis is true. \"Be careful\" is not a\ncheck. \"Look more closely\" is not a check. `getComputedStyle(el).position` is a\ncheck, and CI rejects the first two automatically.\n\nOpen an issue or a PR against `registry.json`. Full guide in\n[CONTRIBUTING.md](CONTRIBUTING.md); the field reference is\n[`schema/registry.schema.json`](schema/registry.schema.json).\n\n```bash\npython3 tools/validate.py            # structure + editorial rules\ncd mcp && python3 test_server.py     # server still works\npython3 build.py dist/               # site still builds\n```\n\n## Building\n\n```bash\npython3 build.py dist/\n```\n\nEvery page — HTML, plain text, JSON, JSONL, `llms.txt`, sitemap — is generated\nfrom `registry.json`. There is no second copy of the content to fall out of\ndate, which is the registry's own first principle applied to itself.\n\n## Licence\n\nCC0-1.0. Public domain. Copy it, quote it, fold it into a system prompt, ship\nit inside a product. No attribution required.\n\n---\n\nMaintained by [Zion Labs](https://zionlabs.io) · [verifyfirst.dev](https://verifyfirst.dev)\n",
  "bytes": 6943,
  "sha": "5db1eb815000c10ff84bfba42f71a06e8a74663d8db4ef1f9cfdefbc1a36afb3",
  "repo_slug": "simulacra/verifyfirst",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_simulacra_verifyfirst_ee33c5f7/readme"
}