AllanWessels Pre-Handoff Clean State Proof
When to use
- You are about to tell the user "the fix is in, go retest."
- You just ran a verifier agent and are merging its report.
- You wiped state (disk, config, vector store) and restarted a server.
- Any situation where you are claiming the system is in a known-good state.
When NOT to use
- The change was purely to a documentation file or SKILL.md with no runtime effect.
- You are handing off a work-in-progress explicitly labeled as such.
How to apply
The pattern
Build a numbered checklist specific to your project. Each item has three parts:
- The command to run (real curl, ls, test -e — no "I believe" language).
- The expected output (exact string or HTTP status code).
- The action if it fails (fix it — do not hand off).
Generic template
Adapt these to your stack. Every item must be verified by a real command:
Pre-handoff checklist — run every item, read every output:
1. Backend health:
curl -sf http://127.0.0.1:<port>/api/health
→ Expected: HTTP 200, body {"ok":true}
2. App state reset:
curl -sf http://127.0.0.1:<port>/api/setup/state
→ Expected: config_exists: false, setup_completed: false
3. Frontend reachable:
curl -I http://127.0.0.1:5173/
→ Expected: HTTP 200
4. Ephemeral config gone:
test -e <config_file> && echo STILL || echo gone
→ Expected: gone
5. Ephemeral DB gone:
test -e <db_dir> && echo STILL || echo gone
→ Expected: gone
6. Data directories empty:
ls <data_dir>/
→ Expected: empty or only README
7. Reports clean:
ls reports/run-*.json 2>&1
→ Expected: "No such file or directory"
8. Frontend module currency (anti-stale-HMR check):
curl -sS http://127.0.0.1:5173/src/<recently-changed>.tsx | head -5
Compare against: head -5 <path-to-file>
→ Expected: byte-for-byte match
9. Store round-trip (catches stale in-memory clients):
curl -sf -X POST http://127.0.0.1:<port>/api/corpus/search \
-d '{"query":"x","k":1}' -H "Content-Type: application/json"
→ Expected: HTTP 200 (not 500), even against empty store
The rule
If ANY check fails, fix it before handing off. "I think item 6 is probably fine" is the failure mode this checklist exists to prevent.
Do not selectively run "the important ones." Run all of them. The one you skip is the one that bites the user.
Adapting the checklist
For a different stack, the structural items to cover are always:
| Category | What to check |
|---|---|
| Process health | Does the server respond? |
| State reset | Are config / setup artifacts gone? |
| Ephemeral data | Are test-generated files gone? |
| Module cache | Does the dev server serve current code? |
| Data layer | Does a round-trip query work against a clean store? |
Adding project-specific items
When a new class of state-poisoning failure is discovered (see [[verifier-state-vs-user-state]]), add it to the checklist immediately. The checklist grows; it never shrinks.
Why this works
The failure mode this skill prevents is confidence based on memory: "I ran that fix, so the state must be clean." Memory is wrong. State-poisoning bugs are characterized by being invisible until the user triggers them — the exact moment the user takes back control. Running the checklist forces the system to express its state in real output, which cannot be wrong in the way that memory can.
Anti-patterns to avoid
- "I think the state is clean" — the entire reason this skill exists. Think nothing; measure everything.
- Running the checklist mentally without executing the commands — counts as not running the checklist.
- Partial checklist — "I already checked 1–4 earlier" — re-run everything. State can change between "earlier" and now.
- Reporting checklist results without the actual output — the output is the proof, not the claim that it passed.
Cross-links
- [[verifier-state-vs-user-state]] — why state can be dirty even after a disk wipe
- [[subprocess-isolation-for-process-state-clients]] — the structural fix that makes several checklist items more reliable
- [[parallel-fanout-verification]] — run the full harness before reaching this checklist; this checklist is the final gate