AGENT SKILL

verify-before-complete

Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.

License 许可
MIT
所属仓库
open-gsd/gsd-pi
最近更新
2026-11-15
Stars
★ 1.4k
Forks
118

01 前言 Front Matter

name
verify-before-complete
description
Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.

03 SKILL.md 正文

<objective> Enforce the GSD "work is not done when code compiles; work is done when verification passes" contract. A completion claim without verification output generated in the current message is a broken claim. This skill is the gate. </objective>

<context> GSD's system prompt sets the expectation; complete-slice.md and auto-verification.ts enforce it at the slice boundary. But between slice boundaries — mid-task, mid-debug, mid-review — an agent can drift into "I think it works" mode and ship broken work. This skill is the ritual to break that pattern at any completion point.

Invocation points:

  • About to toggle a checkbox from [ ] to [x] via a gsd_* tool
  • About to commit, push, or open a PR
  • About to summarize a task or slice as complete
  • About to say "tests pass", "build works", "lint clean", "fixed", "done"
  • Replying to a user question with "yes it works" or similar </context>

<core_principle> EVIDENCE BEFORE CLAIMS, ALWAYS. "I ran it earlier" is not evidence. A log from three tool calls ago is not evidence if code has changed since. The verification must have happened after the last code change, in this message, with fresh output.

VIOLATING THE LETTER IS VIOLATING THE SPIRIT. If the principle feels inconvenient, that is the signal it is load-bearing. Find the verification command. Run it. Read the output. </core_principle>

<process>

Step 1: Identify the claim

What are you about to claim? Name it precisely:

  • "Tests pass" → which tests?
  • "Build works" → for which target?
  • "Bug is fixed" → which reproduction?
  • "Task complete" → which acceptance criteria?

Step 2: Identify the verification command

Match claim → command:

Claim Verification
Tests pass The specific test command the project uses (npm test, cargo test, pytest, etc.) — scoped to changed code if large suite.
Build works The project's build command, for real — not tsc --noEmit if the project needs a bundle.
Lint clean lsp diagnostics on edited files, plus the project's linter if CI runs one.
Bug fixed The reproduction steps from the bug report or test, freshly run.
UI works Browser verification via browser_snapshot_refs + browser_assert in a running app — not "it looks right in the diff".
Slice complete Every acceptance criterion in S##-PLAN.md, re-checked against live behavior.

If no verification command exists, the task has not produced a falsifiable claim — it is not complete. Write the verification first (see the tdd or test skill).

Step 3: Run it now

Use async_bash for one-shot commands, bg_shell for long-running servers/watchers. Wait for it to exit. Read the output. Not skim — read.

If output indicates failure: you do not have a completion claim. Loop back: inspect the error, fix, re-run until it passes or a real blocker requires user input. Do not partially claim ("tests mostly pass") — either pass or report failure honestly.

If output indicates success: quote the relevant line in your reply. "42 tests passing" or "Exit code 0" or "LSP reports 0 errors on the 3 edited files."

Step 4: Check for staleness

If you ran the verification early in this message, then made further code changes, the output is stale. Re-run. Cancel in-flight async_bash jobs that predated the edit (see system prompt: "stale job hygiene").

Step 5: Now claim

Only now, after fresh output, can you:

  • Mark a task/slice/milestone complete via gsd_*
  • Commit / push / open PR
  • State "done", "fixed", "passes", "works"

Include the evidence in the claim: "Slice complete — npm test passed (84/84), npm run build exit 0, acceptance criterion 3 verified against live UI at /dashboard."

</process>

<anti_patterns>

  • "It should work" — not verification. Run the command.
  • "Tests passed earlier" — stale. Run them now.
  • "The code looks right" — code review is not verification.
  • tsc --noEmit as the build check when the project bundles — test what the user experiences.
  • Silent failures — "the test was killed by a timeout so I assume it's fine." No.
  • Partial passes — 80/84 is not "tests pass." Report the 4 failures.
  • Skipping because "I know why this works" — your mental model is not evidence.

</anti_patterns>

<success_criteria>

  • [ ] The claim is precise — not "it works" but "npm test passed with 84/84 tests."
  • [ ] The verification command ran after the last code change, in this message.
  • [ ] Output was read, not skimmed.
  • [ ] Failures would have been caught — the verification actually tests what the claim asserts.
  • [ ] Relevant evidence is quoted in the claim reply.

</success_criteria>

04 同仓库更多 Skills

open-gsd
open-gsd/gsd-pi

write-milestone-brief

Synthesize the current conversation into a milestone brief (PRD). Saves it as the milestone CONTEXT (`gsd_summary_save`) by default, or files a GitHub issue only with explicit user confirmation. Use when asked to "turn this into a PRD", "draft a milestone brief", "capture this context", "write it up", or when enough has been discussed to commit the plan to paper. Does not interview — it synthesizes what is already known.

★ 1.4k
open-gsd
open-gsd/gsd-pi

write-docs

Collaborative authoring workflow for proposals, technical specs, decision docs, READMEs, ADRs, and long-form prose that must work for fresh readers. Three stages: gather context, iterate on structure, reader-test for a stranger. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a doc must be understandable without this session's context.

★ 1.4k
open-gsd
open-gsd/gsd-pi

web-quality-audit

Comprehensive web quality audit covering performance, accessibility, SEO, and best practices. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website".

★ 1.4k
open-gsd
open-gsd/gsd-pi

web-design-guidelines

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

★ 1.4k
open-gsd
open-gsd/gsd-pi

userinterface-wiki

UI/UX best practices for web interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings.

★ 1.4k
open-gsd
open-gsd/gsd-pi

test

Generate or run tests. Auto-detects test framework, generates comprehensive tests for source files, or runs existing test suites with failure analysis.

★ 1.4k