Spike to Falsify, Not to Demo
Type: Open-source — client-agnostic methodology, no project-specific detail.
Created by akbarsha — https://github.com/iamakbarsha1
Distilled from an onchain spike where web research returned correct contract
signatures, but the behaviours that actually shaped the design were only caught
by executing against the deployed bytecode.
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
Docs and research tell you the API shape; only executing against the
production artifact tells you its behaviour. A spike exists to try to
falsify your design assumptions — run the operation you believe is
impossible, forbidden, or already handled — not to demo the happy path. A spike
that only shows the thing working has tested nothing you were worried about.
Checks
- Execute against the real deployed artifact, not a mock or a local
redeploy. Run against the live network (fork it), the real API endpoint, or
the actual published package version — a local reimplementation inherits your
assumptions instead of exposing the vendor's. (Web research returned correct
contract signatures, but 1-based indexing and mandatory filter arguments only
surfaced when calling the deployed bytecode on an anvil fork of the testnet.)
- Run at least one deliberate falsification. Name the property your design
depends on (immutable, soulbound, idempotent, read-only) and attempt the
operation that would violate it; observe what actually happens rather than
what the docs imply. (A token assumed soulbound was in fact transferable —
caught only by attempting the transfer, before a whole access model was built
on the false assumption.)
- Keep an honest friction log. Record every surprise, gotcha, and dead end
in the findings doc, not just the path that worked — the friction is the
reusable output of a spike. (anvil's well-known default accounts carry
contract code on public testnets, which silently breaks
_safeMint's
onReceived callback; the fix — fund fresh EOAs with anvil_setBalance — is
worthless to the next spike unless it's written down.)
Pre-flight check — before you trust a spike's conclusions
If any box is unchecked, you have a demo, not a spike — go try to break the
assumption you're about to build on.
1---2name: spike-falsification3description: Use when validating a third-party dependency — an API, SDK, contract, or protocol — before designing on top of it, especially onchain/smart-contract dependencies. Triggers on "spike this integration", "validate this contract/SDK before we build on it", "is this really soulbound / non-transferable / read-only", "prove the API behaves like the docs say", "fork the network and test against the deployed contract", or any request to de-risk a dependency before committing to a design.4---56# Spike to Falsify, Not to Demo78**Type:** Open-source — client-agnostic methodology, no project-specific detail.910**Created by akbarsha — https://github.com/iamakbarsha1**1112Distilled from an onchain spike where web research returned correct contract13signatures, but the behaviours that actually shaped the design were only caught14by executing against the deployed bytecode.1516**Licence:** Released under CC BY 4.0 — share and adapt for any purpose with17credit. Full text: `LICENSE` at the repository root.1819**Feedback & Support:** If a rule here proves wrong or needs sharpening, open an20issue on the repository or contact the author at the profile link above. If the21problem is the agent not following a rule below rather than the rule itself,22that's an execution failure — acknowledge and correct it.2324## The core rule2526Docs and research tell you the API *shape*; only executing against the27production artifact tells you its *behaviour*. A spike exists to try to28**falsify** your design assumptions — run the operation you believe is29impossible, forbidden, or already handled — not to demo the happy path. A spike30that only shows the thing working has tested nothing you were worried about.3132## Checks3334- **Execute against the real deployed artifact, not a mock or a local35 redeploy.** Run against the live network (fork it), the real API endpoint, or36 the actual published package version — a local reimplementation inherits your37 assumptions instead of exposing the vendor's. *(Web research returned correct38 contract signatures, but 1-based indexing and mandatory filter arguments only39 surfaced when calling the deployed bytecode on an anvil fork of the testnet.)*40- **Run at least one deliberate falsification.** Name the property your design41 depends on (immutable, soulbound, idempotent, read-only) and attempt the42 operation that would violate it; observe what actually happens rather than43 what the docs imply. *(A token assumed soulbound was in fact transferable —44 caught only by attempting the transfer, before a whole access model was built45 on the false assumption.)*46- **Keep an honest friction log.** Record every surprise, gotcha, and dead end47 in the findings doc, not just the path that worked — the friction is the48 reusable output of a spike. *(anvil's well-known default accounts carry49 contract code on public testnets, which silently breaks `_safeMint`'s50 onReceived callback; the fix — fund fresh EOAs with `anvil_setBalance` — is51 worthless to the next spike unless it's written down.)*5253## Pre-flight check — before you trust a spike's conclusions5455- [ ] The spike ran against the real deployed artifact (forked live network for56 onchain), not a mock, stub, or local redeploy.57- [ ] You attempted at least one operation your design assumes cannot happen,58 and recorded the actual result — not the documented one.59- [ ] The findings doc logs every surprise and gotcha hit, not only the60 happy-path result.61- [ ] Any check whose grounding case is domain-specific (e.g. anvil/EVM) was62 applied as an example of the pattern, not copied verbatim to an unrelated63 stack.6465If any box is unchecked, you have a demo, not a spike — go try to break the66assumption you're about to build on.
iamakbarsha1