| name | verify |
| description | Execute VERIFY.md scenarios through real consumer paths, review the frozen task-owned diff, deliver the verdict, and close the bundle — distilling durable lessons into the repo's MEMORY.md. Also the route for re-running an open bundle's gates or updating its VERIFY.md/NOTES.md, including after another agent's commits — never by ad-hoc scripts. For an open bundle only; tier-Light changes are verified inline, not through this skill. |
verify
Turn evidence into a verdict, then close.
Precondition: an open bundle with a drafted VERIFY.md. No bundle → the
change is tier Light; verify the changed surface inline and skip this skill.
Verify
- Cross-check coverage before running anything: every behavior in the SPEC's
Testing Decisions has a red test that went green, every red test maps to a
VERIFY.md scenario or repo check, and every scenario traces back to a
SPEC behavior or Anti-goal. An orphan on any side is a gap — record it and
surface it; do not silently proceed past it.
- Run every
VERIFY.md scenario through the real consumer path at its seam;
record command, output, and PASS/FAIL per scenario.
- Run the repo's checks for the touched surface: tests, lint, types, build.
- Freeze and review the task-owned diff: every changed line traces to SPEC
scope; nothing unrelated is staged.
- For risky seams, spot-check assertion strength: hand-flip 2–3 mutants in
the new logic (invert a condition, off-by-one a boundary, drop a call) —
the suite must go red each time. A surviving mutant is a missing or weak
test, and a FAIL of the red list.
- Record deviations and risks. Contradictions or unavailable proof are
surfaced, never silently marked passed. A scenario that cannot be executed
as written goes back to
spec for a checkable rewrite — do not invent a
substitute measurement. The scenario list is frozen once this pass starts:
scenarios gain results here, never rewrites or removals.
- Write the verdict last. A passing command is evidence;
VERIFY.md owns the
verdict.
For substantial diffs, run this skill in a fresh context — a new session or a
subagent that reads only the bundle and the diff. The implementer verifying
their own work invites confirmation bias. A dispatched subagent never fixes
anything: mutants it flips are reverted before reporting, and on FAIL it
records the verdict and stops — routing back to implement belongs to the
parent turn that holds the user's ask. A subagent that fails to start or
report is a dispatch failure, not evidence: fall back to running the
checklist in this session instead of polling for it.
Red flags
| The thought | The reality |
|---|
| "It obviously passes — running it is a formality" | Scenarios exist because "obviously" has been wrong before. Run every one and record the output. |
| "The scenario can't run as written, but this similar check proves the same thing" | That is a substitute measurement. Route back to spec for a checkable rewrite. |
| "The mutant survived, but the code is clearly fine" | A surviving mutant is a weak or missing test, and a FAIL of the red list. |
| "I wrote this diff — I know it works" | That is the confirmation bias the fresh-context rule exists for. |
| "I'll just fix this small failure while I'm verifying" | Verify delivers a verdict, never fixes. A FAIL routes back to implement. |
Close (on PASS, with durable ship or handoff proof)
- Append a dated close-out line to
NOTES.md citing the ship evidence
(commit hashes or handoff target).
- Sweep the SPEC's Implementation Decisions: any that is hard to reverse,
surprising without context, AND a real trade-off — and has no ADR yet —
is promoted to
.waymark/adr/NNNN-<slug>.md with an index line in
MEMORY.md, before the bundle is buried in the archive.
- Append 2–3 distilled lines to
.waymark/MEMORY.md — invariants
discovered, decisions and their why, gotchas — each linking to the bundle.
Prune stale entries in the same edit; keep the index ≤200 lines. Offer the
user one line: the new lessons by name, and that coach can teach the
concept behind any of them grounded in this repo.
mv .waymark/active/<work-id> .waymark/archive/<work-id>.
When the verdict passes but the ship commit has not landed yet, do not leave
the close implicit: set NOTES.md Next Action to "commit, then close bundle".
The turn that lands the commit performs the close in that same turn — a PASS
bundle never stays in active/ across sessions.
On FAIL: back to implement with the failing scenarios noted in NOTES.md
and this pass appended to its Attempts list. Never close on a FAIL, and never
stage or commit bundle contents. A scenario still failing after three
implement passes — counted from Attempts, across sessions — is a SPEC problem,
not an implementation one: stop and re-settle the decision via
scout/spec.
