fix(pstack): create-verification-skill proves a fresh target, not a warm one

Draft
SI
6d ago
+3-2

Why

We run create-verification-skill output against disposable cloud VMs that start empty. Three things the generated skill allowed went wrong there:

  1. False ready. A Postgres health check over the Unix socket reported healthy at 3 s while init scripts were still running; TCP readiness became healthy at 19 s, after init. The first drive hit a missing role.
  2. Weakened journeys. A publish journey could not succeed on seed data (a certification precondition the seed lacks). The temptation is to trim the journey until it passes.
  3. Stand-in proofs. A container stood in for a fresh VM and passed because the harness created /run/sshd by hand. Real VMs then failed the same step.

What changes

In pstack/skills/create-verification-skill/SKILL.md only, one sentence each:

  • Launch: reach a usable state from an empty data dir (migrations, seed), and readiness means that state.
  • Gotchas (new bullet in step 2): a seed-blocked journey reports failure with the reason in the feature's Gotchas; never weaken it.
  • Step 4: steps a stand-in performs that the real target will not stay unverified until a run on the real target covers them.

Opened as a draft for your call on wording and placement.

[!NOTE]
Low Risk
Documentation-only change to an internal skill generator; no runtime or product code paths affected.

Overview
Tightens the create-verification-skill generator doc so verification skills are written and proven against empty/fresh targets, not warmed-up dev machines.

Launch now requires reaching a usable state from an empty data dir (migrations/seed), with readiness defined as that state—not merely a process or shallow health check (e.g. DB socket healthy while init still runs).

Generated skills gain a Gotchas section: seed-blocked user journeys must fail with a documented reason in the feature map’s Gotchas, not be trimmed until they pass.

Step 4 (prove before handoff) adds that stand-in environments (container vs VM, local vs remote) must enumerate setup the stand-in did that the real target won’t; those steps stay unverified until exercised on the real target.

Reviewed by Cursor Bugbot for commit 640954a21345cdfc74625b1f53f39fff0d7fda30. Bugbot is set up for automated code reviews on this repo. Configure here.